NXContextAlloc

Allocates and initializes a context structure.

Library:LibC
Classification:NKS
Service:Threads

Syntax

  #include <nks/thread.h>
   
  NXContext_t NXContextAlloc (
     void              (*start_routine)(void  *arg), 
     void               *arg, 
     int                 priority, 
     size_t              stackSize,
     unsigned long       flags, 
     int                *error);

Parameters

start_routine

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

arg

(IN) Points to the parameter for the start_routine.

priority

(IN) Specifies the priority of the context:

Flag

Value

Description

NX_PRIO_HIGH

10

High priority

NX_PRIO_MED

5

Medium priority

NX_PRIO_LOW

1

Low priority

NOTE:Because the NetWare® scheduler does not currently support priority, this flag has no effect on NetWare.

stackSize

(IN) Specifies the execution stack size for the context. If set to 0, a default-sized stack of 16384 is allocated or the size specified at link time.

flags

(IN) Specifies the context flags:

Decimal

Constant

Description

0

NX_CTX_NORMAL

Normal context-can be bound to an application thread. Only contexts of this type may be passed to NXThreadCreate.

1

NX_CTX_WORK

Work context-can be bound only to an anonymous thread. Only contexts of this type may be passed to NXWorkSchedule and NXDelayedWorkSchedule
error

(OUT) Points to the location to be set with the error number. This can be set to NULL if you aren't interested in any possible error codes.

Return Values

If successful, returns a pointer to the allocated context. Otherwise, returns a NULL pointer and sets the error parameter one of the following (if the error parameter was not passed as NULL):

Decimal

Hex

Constant

Description

5

0x05

NX_ENOMEM

Insufficient memory to complete this call.

9

0x09

NX_EINVAL

The priority or flags parameter is invalid (or possibly both are).

Remarks

NXContextAlloc allocates and initializes an execution context, which encapsulates all of the run-time state for a thread (as tracked by the virtual machine).

NOTE:The notion of priority is associated with contexts, not with threads. A thread assumes the priority of the context it is currently hosting.

A newly created context must be hosted by a thread to begin execution:

  • Contexts created with the NX_CTX_NORMAL flag are associated with an application thread by calling NXThreadCreate.

  • Contexts created with the NX_CTX_WORK flag are scheduled for execution by anonymous threads by calling NXWorkSchedule or NXDelayedWorkSchedule.

When an application thread returns from the function specified in the start_routine parameter, the thread hosting the context is terminated. The hosted context might be destroyed, depending on how the thread was created (see NXThreadCreate).

When an anonymous thread returns from the function specified in the start_routine parameter, the thread hosting the context can be terminated, but it might not be. If the context is not automatically destroyed, all active key-value pairs associated with the context are cleaned up. The context state is set to execute the function that was established when the context was last initialized. The application must manage the context and free it appropriately. Work contexts can then be legally rescheduled.

For sample code, see ThrCreat.c.

See Also