NXThreadCreateSx

Syntax

  #include <nks/thread.h>
   
  int NXThreadCreateSx (
     void          (*start_routine)(void *arg),
     void           *arg,
     unsigned long   thread_flags,
     NXContext_t    *ctx,
     NXThreadId_t   *thr);
  

Parameters

start_routine

Points to the function to be executed. The arg parameter specifies the argument to be passed to the start_routine.

arg

Points to the parameter for the start_routine.

thread_flags

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. 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. 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.
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.

ctx

(OUT) Points to a context structure specifying the run-time state of the thread.

thr

(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 NXThreadCreateSx function encodes calls to both NXContextAlloc and NXThreadCreate for use when an abbreviation of the two is useful in creating an application thread. The context is created with the following characteristics:

The priority can be changed with NXThreadSetPriority; the stack size and context type cannot be changed.

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.

See Also

• NXContextAlloc
• NXThreadCreate
• NXThreadExit

Example

  #include <stdio.h>
  #include <nks/thread.h>
  void start( void *arg )
  {
     printf(“This is printed by the new, detached thread!\n”);
     printf(“The value printed here should be 99: %d\n”, (int) arg);
  }
  int print99foo( NXThreadId_t *id )
  {
     int          err;
     NXContext_t  ctx;
     NXThreadId_t thr;
     err = NXThreadCreateSx(start, (void *) 99, NX_THR_DETACHED, &ctx,
                            &thr);
     if (err)
        return err;
     *id = thr;
     return 0;
  }