Changeset 8020 in vbox for trunk/include

Timestamp:

Apr 16, 2008 10:14:39 AM (17 years ago)

Author:

vboxsync

svn:sync-xref-src-repo-rev:

29679

Message:

Main/Settigs: Disabled File (..., RTFILE aHandle, ...) constructor since it is not thread-safe when the handle is shared across different File instances (needs a handle duplicate operation in the IPRT File API).

File:

• trunk/include/VBox/settings.h (modified) (5 diffs)

trunk/include/VBox/settings.h

@@ -81 +81 @@
  * Making deep copies or detaching the existing shallow copy from its original
  * is not yet supported.
+ *
+ * Note that the Settings File API is not thread-safe. It means that if you
+ * want to use the same instance of a class from the settings namespace on more
+ * than one thread at a time, you will have to provide necessary access
+ * serialization yourself.
  *
  * Due to some (not propely studied) libxml2 limitations, the Settings File
@@ -1171 +1176 @@
  * regular files.
  *
- * The File class uses IPRT File API for file operations.
+ * The File class uses IPRT File API for file operations. Note that IPRT File
+ * API is not thread-safe. This means that if you pass the same RTFILE handle to
+ * different File instances that may be simultaneously used on different
+ * threads, you should care about serialization; otherwise you will get garbage
+ * when reading from such File instances.
+ *
+ * @todo We should duplicate file handles (once this API is in IPRT) passed to
+ *       constructors to provide thread-safety.
  */
 class VBOXSETTINGS_CLASS File : public Input, public Output
@@ -1192 +1204 @@
     File (Mode aMode, const char *aFileName);
 
+#if 0
+    /// @todo disabled until made thread-safe by using handle duplicates
     /**
      * Uses the given file handle to perform file operations. The given file
@@ -1204 +1218 @@
      * this object destruction.
      *
+     * @note It you pass the same RTFILE handle to more than one File instance,
+     *       please make sure you have provided serialization in case if these
+     *       instasnces are to be simultaneously used by different threads.
+     *       Otherwise you may get garbage when reading or writing.
+     *
      * @param aHandle   Open file handle.
      * @param aMode     File mode of the open file handle.
-     * @param aFileName File name (for reference).
-     */
-    File (Mode aMode, RTFILE aHandle, const char *aFileName = NULL);
+     * @param aFileName File name (for reference, may be NULL).
+     */
+    File (Mode aMode, RTFILE aHandle, const char *aFileName);
+#endif
 
     /**
@@ -1282 +1302 @@
 /**
  * The XmlTreeBackend class uses XML markup to store settings trees.
+ *
+ * @note libxml2 and libxslt libraries used by the XmlTreeBackend are not
+ * fully reentrant. To "fix" this, the XmlTreeBackend backend serializes access
+ * to such non-reentrant parts using a global mutex so that only one thread can
+ * use non-reentrant code at a time. Currently, this relates to the #rawRead()
+ * method (and to #read() as a consequence). This menas that only one thread can
+ * parse an XML stream at a time; other threads trying to parse same or
+ * different streams using different XmlTreeBackend and Input instances
+ * will have to wait.
+ *
+ * Keep in mind that the above reentrancy fix does not imply thread-safety: it
+ * is still the caller's responsibility to provide serialization if the same
+ * XmlTreeBackend instnace (as well as instances of other classes from the
+ * settings namespace) needs to be used by more than one thread.
  */
 class VBOXSETTINGS_CLASS XmlTreeBackend : public TreeBackend