+ +

Threads

Threads provide a means of representing multiple parallel execution contexts. +NNG makes use of this concept internally, but also provides for user applications +to utilize the same thread facilities. This allows one form of concurrency for +applications.

+ + note +

Threads in NNG are built upon platform support, which may be based upon operating +system supplied threads, process, or coroutines. The appearance of concurrency does +not guarantee true concurrency, and scheduling between threads may not necessarily be +pre-emptive. While this will not adversely impact applications that use this facility +for I/O bound concurrency, it may not provide good results for purely CPU-bound operations.

+ + important +

Thread objects created by this function may not be real system-level +threads capable of performing blocking I/O operations using normal blocking system calls. +If use of blocking system calls is required (not including APIs provided +by the NNG library itself of course), then real OS-specific threads +should be created instead (such as with pthread_create or similar functions.) +Blocking NNG library calls can however be made safely from NNG threads.

+ + tip +

The system may impose limits on the number of threads that can be created. +Typically applications should not create more than a dozen of these. +If greater concurrency or scalability is needed, consider instead using +an asynchronous model using nng_aio structures.

Thread Structure

typedef struct nng_thread nng_thread;
+

The nng_thread structure represnts a thread, which is a single execution context. +A given thread will have its own stack, and CPU registers. However global state, as well +as values allocated on the heap, will be shared and accessible to all threads in the system +(See the Synchronization chapter for functions to help with data sharing between different threads.)

Multiple threads can be thought of as running concurrently, even though +they might not actually do so.

I/O operations that block (i.e. wait for completion) will block the +thread, while allowing other threads to proceed.

Creating a Thread

int nng_thread_create(nng_thread **thrp, void (*func)(void *), void *arg);
+

The nng_thread_create function creates a thread, which will execute func, with +the given argument arg, and returns a pointer to it in thrp.

The thread may begin execution immediately.

The thread will persist until func returns.

This function returns zero on success, but may return NNG_ENOMEM if insufficient +resources to create a thread are available.

Destroying a Thread

void nng_thread_destroy(nng_thread *thr);
+

The nng_thread_destroy function waits for the thread thr to finish execution. +This function should be called to reclaim any resources associated with the thread when done. +It also has the effect of blocking execution in the caller until thr has completed executing.

Thread Names

void nng_thread_set_name(nng_thread *thr, const char *name);
+

In order to facilitate debugging, nng_thread_set_name may be called +to provide a name for the thread. This may change how the thread is represented +in debuggers. Not all platforms support setting the thread name.

NNG Reference Manual (DRAFT)

Threads

Thread Structure

Creating a Thread

Destroying a Thread

Thread Names

See Also