= nng_cv_wait(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_cv_wait - wait for condition

== SYNOPSIS

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

void nng_cv_wait(nng_cv *cv);
----

== DESCRIPTION

The `nng_cv_wait()` waits for the condition variable _cv_ to be signaled
by another thread calling either xref:nng_cv_wake.3supp.adoc[`nng_cv_wake()`] or
xref:nng_cv_wake1.3supp.adoc[`nng_cv_wake1()`].

The caller must have have ownership of the mutex that was used when
_cv_ was allocated.
This function will drop the ownership of that mutex, and reacquire it
atomically just before returning to the caller.
(The waiting is done without holding the mutex.)

NOTE: Any condition may be used or checked, but the condition must be
checked, as it is possible for this function to wake up "`spuriously`".
The best way to do this is inside a loop that repeats until the condition
tests for true.

== EXAMPLE

The following example demonstrates use of this function:

.Example 1: Waiting for the condition
[source, c]
----

    nng_mtx_lock(m);  // assume cv was allocated using m
    while (!condition_true) {
        nng_cv_wait(cv);
    }
    // condition_true is true
    nng_mtx_unlock(m);
----

.Example 2: Signaling the condition
[source, c]
----
    nng_mtx_lock(m);
    condition_true = true;
    cv_wake(cv);
    nng_mtx_unlock(m);
----

== RETURN VALUES

None.

== ERRORS

None.

== SEE ALSO

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