Changeset 48297 in vbox for trunk/doc/manual

Timestamp:

Sep 5, 2013 9:57:44 AM (11 years ago)

Author:

vboxsync

Message:

Main/Medium: redesign API level medium locking, needed conversions from MediaList to MediumLockLists in several places, forced cleanups elsewhere, too
Main/Token: introduced token objects for controlling the unlocking, will be used as a general concept in the future
Main/Snapshot: snapshot deletion needed significant cleanups as it was still using many shortcuts, directly calling the API to lock media instead of using lock lists. Now much better, and the online snapshot deletion is also a lot cleaner as it no longer passes unnecessary parameters around which are already known in the machine/snapshot code
Main/MediumLock: small improvements, now has a mode which skips locking already locked media, needed by the Snapshot code where we have overlapping lock lists and have to update the original one instead
Main/Console+Session+Machine: follow-up changes for the online snapshot merging parameter passing simplification, plus an unrelated lock order violation fix in Machine which happens only for inaccessible machines
Main/testcase: update correspondingly
doc: update SDK reference

File:

• trunk/doc/manual/en_US/SDKRef.xml (modified) (1 diff)

trunk/doc/manual/en_US/SDKRef.xml

@@ -3531 +3531 @@
       <itemizedlist>
         <listitem>
+          <para>The explicit medium locking methods 
+            <xref linkend="IMedium__lockRead" xreflabel="IMedium::lockRead()" />
+            and <xref linkend="IMedium__lockWrite" xreflabel="IMedium::lockWrite()" />
+            have been redesigned. They return a lock token object reference
+            now, and calling the <xref linkend="IToken__abandon"
+              xreflabel="IToken::abandon()" /> method (or letting the reference
+            count to this object drop to 0) will unlock it. This eliminates
+            the rather common problem that an API client crash left behind
+            locks, and also improves the safety (API clients can't release
+            locks they didn't obtain).</para>
+        </listitem>
+
+        <listitem>
           <para><computeroutput>IMachine::delete</computeroutput>
           has been renamed to <xref linkend="IMachine__deleteConfig"