= nng_mtx_lock(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_mtx_lock - lock mutex

== SYNOPSIS

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

void nng_mtx_lock(nng_mtx *mtx);
----

== DESCRIPTION

The `nng_mtx_lock()` acquires exclusive ownership of the mutex _mtx_.
If the lock is already owned, this function will wait until the current
owner releases it with xref:nng_mtx_unlock.3supp.adoc[`nng_mtx_unlock()`].

If multiple threads are waiting for the lock, the order of acquisition
is not specified.

NOTE: A mutex can _only_ be unlocked by the thread that locked it.

IMPORTANT: Mutex locks are _not_ recursive; attempts to reacquire the
same mutex may result in deadlock or aborting the current program.
It is a programming error for the owner of a mutex to attempt to
reacquire it.

****
_NNG_ offers neither a non-blocking variant that can fail,
nor recursive mutexes.
This is by design, as _NNG_ itself does not use such things,
and most often the need for them is the result of poor design.
If such capabilities are needed, they may be synthesized fairly
easily from mutexes and condition variables.
****

== RETURN VALUES

None.

== ERRORS

None.

== SEE ALSO

[.text-left]
xref:nng_cv_alloc.3supp.adoc[nng_cv_alloc(3supp)],
xref:nng_mtx_alloc.3supp.adoc[nng_mtx_alloc(3supp)],
xref:nng_mtx_unlock.3supp.adoc[nng_mtx_unlock(3supp)],
xref:nng.7.adoc[nng(7)]
