NXThreadCreate

Syntax

  #include <nks/thread.h>
   
  int NXThreadCreate (
     NXContext_t     ctx,
     unsigned long   flags, 
     NXThreadId_t   *idp);
  

Parameters

ctx

(IN) Points to a context structure specifying the run-time state of the thread (must be of type NX_CTX_NORMAL; see NXContextAlloc).

flags

(IN) Specifies the attributes for the new thread. Can be zero or a bitwise OR of the following:

NX_THR_JOINABLE	0x00000000	Create the new thread in a joinable state rather than a detached state. A joinable thread is also referred to as a waitable thread or a non-detached thread. Only joinable threads can be waited for (or “joined”) using the NXThreadJoin interface. This is the default (0).
NX_THR_DETACHED	0x00000010	Create the new thread in a detached state. A detached thread cannot be waited for. A thread created without this flag is defined to be a joinable thread.
NX_THR_SUSPENDED	0x00000020	Create the new thread in a suspended state.
NX_THR_DAEMON	0x00000040	Create a new thread as a daemon thread. Daemon threads are not considered when determining when the last application thread has exited. Daemon threads are always detached; the NX_THR_DETACHED flag must be set when creating a daemon thread.
NX_THR_BIND_CONTEXT	0x00000080	Create a thread (application or daemon) that automatically frees the context object when the thread exits. When this flag is not set, the lifetime of the context that is associated with the thread is independent of the thread itself. This flag should be set unless the application intends to explicitly manage contexts and/or reuse a context object after the thread hosting it exits.

idp

(OUT) Points to the new thread's identifier. If not NULL, the ID of the newly created thread is returned in the location pointed to by thread_id.

Return Values

If successful, returns 0; otherwise, returns a nonzero error code:

Remarks

The new thread has the run-time state specified by the context structure pointed to by context. Only idle contexts that are not in use can be passed.

The priority of a thread is the same as the priority of the context it is currently hosting. Threads do not have priorities independent of their context.

When a thread (daemon or application) is created with the NX_THR_BIND_CTX flag, the thread is permanently bound to the context that is passed in. Such a thread cannot switch the contexts hosted by it by calling NXThreadSwapContext. The context hosted by such a thread is automatically destroyed when the thread terminates.

When thread that is created without the NX_THR_BIND_CTX flag terminates, the context hosted by it is not automatically destroyed. Application threads created this way are not bound to the passed in context and can be switched to a different context by calling NXThreadSwapContext. Because the contexts hosted by the threads created this way are not automatically destroyed when the thread terminates, the application must manage the context and free it appropriately.

If a thread (daemon or application) returns from the starting function specified in the context that is passed to NXThreadCreate, the thread is terminated. If the context hosted by the thread is not automatically destroyed, all active key/value pairs associated with the context are cleaned up and the context state is set to call the function that was established when the context was last initialized.

When a detached thread exists, it will clean up after itself automatically. However, when a joinable thread exists and a thread is not already waiting to join the exiting thread, the system maintains sufficient state to support a subsequent call to NXThreadJoin. If you do not call NXThreadJoin on an exited joinable thread, system resources are held up unnecessarily.

For sample code, see ThrCreat.c.

See Also

• NXContextAlloc
• NXThreadContinue
• NXThreadCreateSx
• NXThreadExit
• NXThreadGetId
• NXThreadJoin
• NXThreadSuspend
• NXThreadSwapContext
• NXWorkSchedule