Changeset 1400 for trunk/src/emx/include/InnoTekLIBC/thread.h

Timestamp:

Apr 29, 2004, 5:35:22 AM (21 years ago)

Author:

bird

Message:

Added thread termination callback functionality.

File:

• trunk/src/emx/include/InnoTekLIBC/thread.h (modified) (3 diffs, 1 prop)

trunk/src/emx/include/InnoTekLIBC/thread.h

@@ -141 +141 @@
 
 
+/**
+ * Thread Termination Callback Registration Record. (cool name, right)
+ * For use with __libc_ThreadRegisterTermCallback().
+ */
+typedef struct __libc_ThreadTermCbRegRec
+{
+    /** This member must be initialized to NULL. */
+    struct __libc_ThreadTermCbRegRec   *pNext;
+    /** Flags field reserved for future use. 
+     * Must be initalized to ZERO.  */
+    unsigned                            fFlags;
+    /** 
+     * The callback function. 
+     *
+     * @param pRegRec   Registration record which the callback was registered with.
+     * @param fFlags    Reserved for future use. Will always be zero when fFlags 
+     *                  in the RegRec is zero.
+     */
+    void                              (*pfnCallback)(struct __libc_ThreadTermCbRegRec *pRegRec, unsigned fFlags);
+} __LIBC_THREADTERMCBREGREC, *__LIBC_PTHREADTERMCBREGREC;
+
+
 /*******************************************************************************
 *   Global Variables                                                           *
@@ -223 +245 @@
 
 
+/** 
+ * Register a thread destruction callback.
+ *
+ * This will be called when one thread is terminating normally, i.e. calling 
+ * _endthread() or returning from it's thread function.
+ * When LIBC implements pthreads basics any new non-abnormal thread exit will 
+ * cause a callback too.
+ *
+ * @param   pRegRec     Pointer to thread registration record.
+ *                      This must be initialized as described in the documation of
+ *                      the structure. After calling this API the memory must not
+ *                      be touched or freed by the application. It is not possible
+ *                      to unregister a callback at present.
+ *
+ * @remark  We might wanna extend the API at a later point for calling back 
+ *          at abnormal termination and such. Such extensions will be done 
+ *          using the fFlags member of __LIBC_THREADTERMCBREGREC and the fFlags
+ *          parameter to the callback.
+ */
+int     __libc_ThreadRegisterTermCallback(__LIBC_PTHREADTERMCBREGREC pRegRec);
+
+/**
+ * Internal API which is called by a thread exit to work the registered callbacks.
+ *
+ * Not called for thread 1.
+ * 
+ * @param   fFlags  Reserved for termination reasons.
+ *                  Zero means normal exit, no other codes have been defined.
+ */
+void    __libc_threadTermination(unsigned fFlags);
+
+
 /** @group InnoTek LIBC Thread Local Storage
  * @{
@@ -263 +317 @@
 int     __libc_TLSSet(int iIndex, void *pvValue);
 
+/** 
+ * Register a thread termination destructor for an TLS entry.
+ *
+ * The destructor function will be called when a thread terminates
+ * in a normal fashion and the TLS entry iTLSIndex of that thread is
+ * not NULL. 
+ *
+ * There will be no callbacks in thread 1.
+ *
+ * @returns 0 on succces.
+ * @returns -1 on failure. errno set.
+ * @param   iTLSIndex       Value returned by __libc_TLSAlloc().
+ * @param   pfnDestructor   Callback function. Use NULL to unregister a previously
+ *                          registered destructor.
+ *
+ *                          It's pvValue argument is the non-zero value in the
+ *                          TLS entry for the thread it's called on.
+ *
+ *                          It's fFlags argument is reserved for future use, it will
+ *                          always be zero when the fFlags parameter to this API is zero.
+ *
+ * @param   fFlags          Flags reserved for future use. At the moment
+ *                          only ZERO is allowed.
+ *
+ * @remark  The application is not allowed to call __libc_TLSFree() for iIndex when calling
+ *          this function. The result from doing that is undefined.
+ */
+int     __libc_TLSDestructor(int iIndex, void (*pfnDestructor)(void *pvValue, unsigned fFlags), unsigned fFlags);
+
 /** @} */
+
 __END_DECLS