pr_createthread.rst (2356B)
1 PR_CreateThread 2 =============== 3 4 Creates a new thread. 5 6 7 Syntax 8 ------ 9 10 .. code:: 11 12 #include <prthread.h> 13 14 PRThread* PR_CreateThread( 15 PRThreadType type, 16 void (*start)(void *arg), 17 void *arg, 18 PRThreadPriority priority, 19 PRThreadScope scope, 20 PRThreadState state, 21 PRUint32 stackSize); 22 23 24 Parameters 25 ~~~~~~~~~~ 26 27 :ref:`PR_CreateThread` has the following parameters: 28 29 ``type`` 30 Specifies that the thread is either a user thread 31 (``PR_USER_THREAD``) or a system thread (``PR_SYSTEM_THREAD``). 32 ``start`` 33 A pointer to the thread's root function, which is called as the root 34 of the new thread. Returning from this function is the only way to 35 terminate a thread. 36 ``arg`` 37 A pointer to the root function's only parameter. NSPR does not assess 38 the type or the validity of the value passed in this parameter. 39 ``priority`` 40 The initial priority of the newly created thread. 41 ``scope`` 42 Specifies your preference for making the thread local 43 (``PR_LOCAL_THREAD``), global (``PR_GLOBAL_THREAD``) or global bound 44 (``PR_GLOBAL_BOUND_THREAD``). However, NSPR may override this 45 preference if necessary. 46 ``state`` 47 Specifies whether the thread is joinable (``PR_JOINABLE_THREAD``) or 48 unjoinable (``PR_UNJOINABLE_THREAD``). 49 ``stackSize`` 50 Specifies your preference for the size of the stack, in bytes, 51 associated with the newly created thread. If you pass zero in this 52 parameter, :ref:`PR_CreateThread` chooses the most favorable 53 machine-specific stack size. 54 55 56 Returns 57 ~~~~~~~ 58 59 The function returns one of the following values: 60 61 - If successful, a pointer to the new thread. This pointer remains 62 valid until the thread returns from its root function. 63 - If unsuccessful, (for example, if system resources are unavailable), 64 ``NULL``. 65 66 67 Description 68 ----------- 69 70 If you want the thread to start up waiting for the creator to do 71 something, enter a lock before creating the thread and then have the 72 thread's root function enter and exit the same lock. When you are ready 73 for the thread to run, exit the lock. For more information on locks and 74 thread synchronization, see `Introduction to 75 NSPR <Introduction_to_NSPR>`__. 76 77 If you want to detect the completion of the created thread, make it 78 joinable. You can then use :ref:`PR_JoinThread` to synchronize the 79 termination of another thread.