= nng_thread_create(3supp)
//
// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
// Copyright 2018 Capitar IT Group BV <info@capitar.com>
//
// This document is supplied under the terms of the MIT License, a
// copy of which should be located in the distribution where this
// file was obtained (LICENSE.txt).  A copy of the license may also be
// found online at https://opensource.org/licenses/MIT.
//

== NAME

nng_thread_create - create thread

== SYNOPSIS

[source, c]
----
#include <nng/nng.h>
#include <nng/supplemental/util/platform.h>

typedef struct nng_thread nng_thread;

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

== DESCRIPTION

The `nng_thread_create()` function creates a single thread of execution,
running _func_ with the argument _arg_.
The thread is started immediately.
A pointer to the thread object is returned in _thrp_.

The intention of this program is to facilitate writing parallel programs.
Threads created by this program will be based upon the underlying
threading mechanism of the system that _NNG_ is running on.
This may include use of coroutines.

Using threads created by this function can make it easy to write
programs that use simple sequential execution, using functions in the
_NNG_ suite that would otherwise normally wait synchronously for completion.

When the thread is no longer needed, the
xref:nng_thread_destroy.3supp.adoc[`nng_thread_destroy()`]
function should be used to reap it.
(This function will block waiting for _func_ to return.)

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

IMPORTANT: Thread objects created by this function cannot be passed
to any system threading functions.

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 xref:nng_aio.5.adoc[`nng_aio`] structures.

TIP: Threads can be synchronized using
xref:nng_mtx_alloc.3supp.adoc[mutexes] and
xref:nng_cv_alloc.3supp.adoc[condition variables].

== RETURN VALUES

This function returns 0 on success, and non-zero otherwise.

== ERRORS

[horizontal]
`NNG_ENOMEM`:: Insufficient free memory exists.

== SEE ALSO

[.text-left]
xref:nng_strerror.3.adoc[nng_strerror(3)],
xref:nng_cv_alloc.3supp.adoc[nng_cv_alloc(3supp)],
xref:nng_mtx_alloc.3supp.adoc[nng_mtx_alloc(3supp)],
xref:nng_thread_destroy.3supp.adoc[nng_thread_destroy(3supp)],
xref:nng_aio.5.adoc[nng_aio(5)],
xref:nng.7.adoc[nng(7)]