pj_threading on external threads (#4626)

Author: LeonidGoltsblat

pjlib/include/pj/os.h

@@ -202,6 +202,33 @@ PJ_DECL(pj_status_t) pj_thread_create(  pj_pool_t *pool,
                                         unsigned flags,
                                         pj_thread_t **thread );
 
+/**
+ * Create a new thread, use preallocated space for thread descriptor
+ * and thread stack.
+ * To avoid pool allocation, function does not support suspended thread.
+ * 
+ *
+ * @param thread_name   The optional name to be assigned to the thread.
+ * @param proc          Thread entry function.
+ * @param arg           Argument to be passed to the thread entry function.
+ * @param stack_size    The size of the stack for the new thread, or ZERO or
+ *                      PJ_THREAD_DEFAULT_STACK_SIZE to let the 
+ *                      library choose the reasonable size for the stack. 
+ * @param stack_addr    Preallocated space of size stack_size for the stack
+ *                      for the new thread, used if PJ_THREAD_ALLOCATE_STACK
+ *                      macro defined and is not 0. Otherwise ignored.
+ * @param thread        Pointer to preallocated thread descriptor to hold
+ *                      the newly created thread.
+ *
+ * @return              PJ_SUCCESS on success, or the error code.
+ */
+PJ_DECL(pj_status_t) pj_thread_create2( const char *thread_name,
+                                        pj_thread_proc *proc, 
+                                        void *arg,
+                                        pj_size_t stack_size, 
+                                        void *stack_addr,
+                                        pj_thread_t *thread );
+
 /**
  * Register a thread that was created by external or native API to PJLIB.
  * This function must be called in the context of the thread being registered.
@@ -222,6 +249,46 @@ PJ_DECL(pj_status_t) pj_thread_register ( const char *thread_name,
                                           pj_thread_desc desc,
                                           pj_thread_t **thread);
 
+
+/**
+ * Detach pjsip library from the current thread without terminating 
+ * the OS thread, frees the resources allocated by pjlib for the calling thread,
+ * including freeing the tls slot in which pj_thread_t is stored.
+ * However, the memory allocated for the pj_thread_t itself will only be released
+ * when the pool used to create the thread is destroyed.
+ * 
+ * An application should call this function when leaving threads created by 
+ * an external module (e.g. audio thread, threads from an external thread pool, 
+ * etc). Such a thread is registered with pj_thread_register() and detached 
+ * with pj_thread_unregister() when finished using.
+ *
+ * @return PJ_SUCCESS on success.
+ */
+PJ_DECL(pj_status_t) pj_thread_unregister();
+
+/**
+ * Register a thread that was created by external or native API to PJLIB.
+ * 
+ * This function is a complete copy of pj_thread_register(), with the only
+ * difference being that on Windows it returns a pj_thread_t suitable for
+ * waiting for the thread to terminate. This function should only be used 
+ * if the application requires calling pj_thread_join() for the current thread;
+ * otherwise, use pj_thread_register().
+ *
+ * @param thread_name   The optional name to be assigned to the thread.
+ * @param desc          Thread descriptor, which must be available throughout 
+ *                      the lifetime of the thread.
+ * @param thread        Pointer to hold the created thread handle.
+ *
+ * @return              PJ_SUCCESS on success, or the error code.
+ * 
+ * @see pj_thread_register()
+ */
+PJ_DECL(pj_status_t) pj_thread_attach ( const char *thread_name,
+                                       pj_thread_desc desc,
+                                       pj_thread_t **thread);
+
+
 /**
  * Check if this thread has been registered to PJLIB.
  *

pjlib/src/pj/os_core_unix.c

@@ -736,33 +736,21 @@ static void *thread_main(void *param)
 
     return result;
 }
-#endif
 
-/*
- * pj_thread_create(...)
- */
-PJ_DEF(pj_status_t) pj_thread_create( pj_pool_t *pool,
-                                      const char *thread_name,
-                                      pj_thread_proc *proc,
-                                      void *arg,
-                                      pj_size_t stack_size,
-                                      unsigned flags,
-                                      pj_thread_t **ptr_thread)
+static pj_status_t create_thread(const char *thread_name,
+                                 pj_thread_proc *proc,
+                                 void *arg,
+                                 pj_size_t stack_size,
+                                 void *stack_addr,
+                                 pj_thread_t *rec)
 {
-#if PJ_HAS_THREADS
-    pj_thread_t *rec;
     pthread_attr_t thread_attr;
-    void *stack_addr;
     int rc;
 
     PJ_UNUSED_ARG(stack_addr);
 
     PJ_CHECK_STACK();
-    PJ_ASSERT_RETURN(pool && proc && ptr_thread, PJ_EINVAL);
-
-    /* Create thread record and assign name for the thread */
-    rec = (struct pj_thread_t*) pj_pool_zalloc(pool, sizeof(pj_thread_t));
-    PJ_ASSERT_RETURN(rec, PJ_ENOMEM);
+    PJ_ASSERT_RETURN(proc && rec, PJ_EINVAL);
 
     /* Set name. */
     if (!thread_name)
@@ -783,19 +771,6 @@ PJ_DEF(pj_status_t) pj_thread_create( pj_pool_t *pool,
     rec->stk_max_usage = 0;
 #endif
 
-    /* Emulate suspended thread with mutex. */
-    if (flags & PJ_THREAD_SUSPENDED) {
-        rc = pj_mutex_create_simple(pool, NULL, &rec->suspended_mutex);
-        if (rc != PJ_SUCCESS) {
-            return rc;
-        }
-
-        pj_mutex_lock(rec->suspended_mutex);
-    } else {
-        pj_assert(rec->suspended_mutex == NULL);
-    }
-
-
     /* Init thread attributes */
     pthread_attr_init(&thread_attr);
 
@@ -811,8 +786,7 @@ PJ_DEF(pj_status_t) pj_thread_create( pj_pool_t *pool,
 
 #if defined(PJ_THREAD_ALLOCATE_STACK) && PJ_THREAD_ALLOCATE_STACK!=0
     /* Allocate memory for the stack */
-    stack_addr = pj_pool_alloc(pool, stack_size);
-    PJ_ASSERT_RETURN(stack_addr, PJ_ENOMEM);
+    PJ_ASSERT_RETURN(stack_addr, PJ_EINVAL);
 
     rc = pthread_attr_setstackaddr(&thread_attr, stack_addr);
     if (rc != 0) {
@@ -834,10 +808,85 @@ PJ_DEF(pj_status_t) pj_thread_create( pj_pool_t *pool,
     /* Destroy thread attributes */
     pthread_attr_destroy(&thread_attr);
 
-    *ptr_thread = rec;
-
     PJ_LOG(6, (rec->obj_name, "Thread created"));
     return PJ_SUCCESS;
+
+}
+
+#endif
+
+/*
+ * pj_thread_create(...)
+ */
+PJ_DEF(pj_status_t) pj_thread_create( pj_pool_t *pool,
+                                      const char *thread_name,
+                                      pj_thread_proc *proc,
+                                      void *arg,
+                                      pj_size_t stack_size,
+                                      unsigned flags,
+                                      pj_thread_t **ptr_thread)
+{
+#if PJ_HAS_THREADS
+    pj_status_t status;
+    pj_thread_t *rec;
+    void *stack_addr = NULL;
+    int rc;
+
+    PJ_CHECK_STACK();
+    PJ_ASSERT_RETURN(pool && proc && ptr_thread, PJ_EINVAL);
+
+    /* Create thread record and assign name for the thread */
+    rec = (struct pj_thread_t*) pj_pool_zalloc(pool, sizeof(pj_thread_t));
+    PJ_ASSERT_RETURN(rec, PJ_ENOMEM);
+
+#if defined(PJ_THREAD_ALLOCATE_STACK) && PJ_THREAD_ALLOCATE_STACK!=0
+    /* Allocate memory for the stack */
+    stack_addr = pj_pool_alloc(pool, stack_size);
+    PJ_ASSERT_RETURN(stack_addr, PJ_ENOMEM);
+#endif  /* PJ_THREAD_ALLOCATE_STACK */
+
+    /* Emulate suspended thread with mutex. */
+    if (flags & PJ_THREAD_SUSPENDED) {
+        rc = pj_mutex_create_simple(pool, NULL, &rec->suspended_mutex);
+        if (rc != PJ_SUCCESS) {
+            return rc;
+        }
+
+        pj_mutex_lock(rec->suspended_mutex);
+    } else {
+        pj_assert(rec->suspended_mutex == NULL);
+    }
+
+    status = create_thread(thread_name, proc, arg, stack_size, stack_addr, rec);
+    if (status == PJ_SUCCESS) {
+        /* Success! */
+        *ptr_thread = rec;
+    }
+    return status;
+
+#else
+    pj_assert(!"Threading is disabled!");
+    return PJ_EINVALIDOP;
+#endif
+}
+
+PJ_DEF(pj_status_t) pj_thread_create2( const char *thread_name,
+                                       pj_thread_proc *proc, 
+                                       void *arg,
+                                       pj_size_t stack_size, 
+                                       void *stack_addr,
+                                       pj_thread_t *thread )
+{
+#if PJ_HAS_THREADS
+
+    PJ_CHECK_STACK();
+    PJ_ASSERT_RETURN(proc && thread, PJ_EINVAL);
+
+    if (thread == pj_thread_this())
+        return PJ_ECANCELLED;
+
+    return create_thread(thread_name, proc, arg, stack_size, stack_addr, thread);
+
 #else
     pj_assert(!"Threading is disabled!");
     return PJ_EINVALIDOP;
@@ -937,12 +986,49 @@ PJ_DEF(pj_status_t) pj_thread_join(pj_thread_t *p)
 #endif
 }
 
+/*
+ * pj_thread_unregister()
+ */
+PJ_DEF(pj_status_t) pj_thread_unregister()
+{
+#if PJ_HAS_THREADS
+    pj_status_t status;
+    //int result;
+    pj_thread_t *rec;
+    PJ_CHECK_STACK();
+
+    rec = pj_thread_this();
+    PJ_ASSERT_RETURN(rec, PJ_EBUG);
+    
+    if ((status = pj_thread_destroy(rec)) != PJ_SUCCESS)
+        return status;
+    //else if ((result = pthread_detach(rec->thread)) != 0)
+    //    return PJ_RETURN_OS_ERROR(result);
+    else
+        return pj_thread_local_set(thread_tls_id, NULL);
+#else
+    pj_assert(!"No multithreading support!");
+    return PJ_EINVALIDOP;
+#endif
+}
+
+/*
+ * pj_thread_attach()
+ */
+PJ_DEF(pj_status_t) pj_thread_attach(const char *cstr_thread_name,
+                                     pj_thread_desc desc,
+                                     pj_thread_t **thread_ptr)
+{
+    return pj_thread_register(cstr_thread_name, desc, thread_ptr);
+}
+
 /*
  * pj_thread_destroy()
  */
 PJ_DEF(pj_status_t) pj_thread_destroy(pj_thread_t *p)
 {
     PJ_CHECK_STACK();
+    PJ_ASSERT_RETURN(p, PJ_EINVAL);
 
     /* Destroy mutex used to suspend thread */
     if (p->suspended_mutex) {
@@ -1005,7 +1091,13 @@ PJ_DEF(void) pj_thread_check_stack(const char *file, int line)
 {
     char stk_ptr;
     pj_uint32_t usage;
-    pj_thread_t *thread = pj_thread_this();
+    pj_thread_t *thread;
+
+    /* may be called after pj_thread_unregister() */
+    if (!pj_thread_is_registered())
+        return;
+
+    thread = pj_thread_this();
 
     /* Calculate current usage. */
     usage = (&stk_ptr > thread->stk_start) ? &stk_ptr - thread->stk_start :