Changeset 43879 in vbox for trunk/include

Timestamp:

Nov 15, 2012 2:49:23 PM (12 years ago)

Author:

vboxsync

Message:

Extended RTOnce with termination cleanups. (Changes existing structures and functions.)

Location:

trunk/include/iprt

Files:

• once.h (modified) (8 diffs)
• runtime-loader.h (modified) (3 diffs)

trunk/include/iprt/once.h

@@ -4 +4 @@
 
 /*
- * Copyright (C) 2006-2007 Oracle Corporation
+ * Copyright (C) 2006-2012 Oracle Corporation
  *
  * This file is part of VirtualBox Open Source Edition (OSE), as
@@ -31 +31 @@
 #include <iprt/asm.h>
 #include <iprt/err.h>
+#include <iprt/list.h>
 
 RT_C_DECLS_BEGIN
@@ -40 +41 @@
 
 /**
+ * Callback that gets executed once.
+ *
+ * @returns IPRT style status code, RTOnce returns this.
+ *
+ * @param   pvUser          The user parameter.
+ */
+typedef DECLCALLBACK(int32_t) FNRTONCE(void *pvUser);
+/** Pointer to a FNRTONCE. */
+typedef FNRTONCE *PFNRTONCE;
+
+/**
+ * Callback that gets executed on IPRT/process termination.
+ *
+ * @param   pvUser          The user parameter.
+ * @param   fLazyCleanUpOk  Indicates whether lazy clean-up is OK (see
+ *                          initterm.h).
+ */
+typedef DECLCALLBACK(void) FNRTONCECLEANUP(void *pvUser, bool fLazyCleanUpOk);
+/** Pointer to a FNRTONCE. */
+typedef FNRTONCECLEANUP *PFNRTONCECLEANUP;
+
+/**
  * Execute once structure.
  *
@@ -48 +71 @@
 {
     /** Event semaphore that the other guys are blocking on. */
-    RTSEMEVENTMULTI volatile hEventMulti;
+    RTSEMEVENTMULTI volatile    hEventMulti;
     /** Reference counter for hEventMulti. */
-    int32_t volatile cEventRefs;
-    /** -1 when uninitialized, 1 when initializing (busy) and 2 when done. */
-    int32_t volatile iState;
+    int32_t volatile            cEventRefs;
+    /** See RTONCESTATE. */
+    int32_t volatile            iState;
     /** The return code of pfnOnce. */
-    int32_t volatile rc;
+    int32_t volatile            rc;
+
+    /** Pointer to the clean-up function. */
+    PFNRTONCECLEANUP            pfnCleanUp;
+    /** Argument to hand to the clean-up function. */
+    void                       *pvUser;
+    /** Clean-up list entry. */
+    RTLISTNODE                  CleanUpNode;
 } RTONCE;
 /** Pointer to a execute once struct. */
@@ -94 +124 @@
 
 /** Static initializer for RTONCE variables. */
-#define RTONCE_INITIALIZER      { NIL_RTSEMEVENTMULTI, 0, RTONCESTATE_UNINITIALIZED, VERR_INTERNAL_ERROR }
-
-
-/**
- * Callback that gets executed once.
- *
- * @returns IPRT style status code, RTOnce returns this.
- *
- * @param   pvUser1         The first user parameter.
- * @param   pvUser2         The second user parameter.
- */
-typedef DECLCALLBACK(int32_t) FNRTONCE(void *pvUser1, void *pvUser2);
-/** Pointer to a FNRTONCE. */
-typedef FNRTONCE *PFNRTONCE;
+#define RTONCE_INITIALIZER \
+    { NIL_RTSEMEVENTMULTI, 0, RTONCESTATE_UNINITIALIZED, VERR_INTERNAL_ERROR, NULL, NULL, { NULL, NULL } }
+
 
 /**
@@ -118 +137 @@
  * @param   pOnce           Pointer to the execute once variable.
  * @param   pfnOnce         The function to executed once.
- * @param   pvUser1         The first user parameter for pfnOnce.
- * @param   pvUser2         The second user parameter for pfnOnce.
- */
-RTDECL(int) RTOnceSlow(PRTONCE pOnce, PFNRTONCE pfnOnce, void *pvUser1, void *pvUser2);
+ * @param   pfnCleanUp      The function that will be doing the cleaning up.
+ *                          Optional.
+ * @param   pvUser          The user parameter for pfnOnce.
+ */
+RTDECL(int) RTOnceSlow(PRTONCE pOnce, PFNRTONCE pfnOnce, FNRTONCECLEANUP pfnCleanUp, void *pvUser);
 
 /**
@@ -132 +152 @@
  * @param   pOnce           Pointer to the execute once variable.
  * @param   pfnOnce         The function to executed once.
- * @param   pvUser1         The first user parameter for pfnOnce.
- * @param   pvUser2         The second user parameter for pfnOnce.
- */
-DECLINLINE(int) RTOnce(PRTONCE pOnce, PFNRTONCE pfnOnce, void *pvUser1, void *pvUser2)
+ * @param   pvUser          The user parameter for pfnOnce.
+ */
+DECLINLINE(int) RTOnce(PRTONCE pOnce, PFNRTONCE pfnOnce, void *pvUser)
 {
     int32_t iState = ASMAtomicUoReadS32(&pOnce->iState);
@@ -142 +161 @@
                   || iState == RTONCESTATE_DONE_HAVE_SEM ))
         return ASMAtomicUoReadS32(&pOnce->rc);
-    return RTOnceSlow(pOnce, pfnOnce, pvUser1, pvUser2);
+    return RTOnceSlow(pOnce, pfnOnce, NULL, pvUser);
 }
+
+/**
+ * Execute pfnOnce once and register a termination clean-up callback.
+ *
+ * Serializes execution of the pfnOnce function, making sure it's
+ * executed exactly once and that nobody returns from RTOnce before
+ * it has executed successfully.
+ *
+ * @returns IPRT like status code returned by pfnOnce.
+ *
+ * @param   pOnce           Pointer to the execute once variable.
+ * @param   pfnOnce         The function to executed once.
+ * @param   pfnCleanUp      The function that will be doing the cleaning up.
+ * @param   pvUser          The user parameter for pfnOnce.
+ */
+DECLINLINE(int) RTOnceEx(PRTONCE pOnce, PFNRTONCE pfnOnce, PFNRTONCECLEANUP pfnCleanUp, void *pvUser)
+{
+    int32_t iState = ASMAtomicUoReadS32(&pOnce->iState);
+    if (RT_LIKELY(   iState == RTONCESTATE_DONE
+                  || iState == RTONCESTATE_DONE_CREATING_SEM
+                  || iState == RTONCESTATE_DONE_HAVE_SEM ))
+        return ASMAtomicUoReadS32(&pOnce->rc);
+    return RTOnceSlow(pOnce, pfnOnce, pfnCleanUp, pvUser);
+}
+
 
 /**

trunk/include/iprt/runtime-loader.h

@@ -4 +4 @@
 
 /*
- * Copyright (C) 2008-2010 Oracle Corporation
+ * Copyright (C) 2008-2012 Oracle Corporation
  *
  * This file is part of VirtualBox Open Source Edition (OSE), as
@@ -116 +116 @@
  * serialised for thread safety.
  */
-static DECLCALLBACK(int) rtldrLoadOnce(void *, void *)
+static DECLCALLBACK(int) rtldrLoadOnce(void *)
 {
     RTLDRMOD    hLib;
@@ -145 +145 @@
 
     LogFlowFunc(("\n"));
-    rc = RTOnce(&s_Once, rtldrLoadOnce, NULL, NULL);
+    rc = RTOnce(&s_Once, rtldrLoadOnce, NULL);
     LogFlowFunc(("rc = %Rrc\n", rc));