= nng_cv_until(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_until - wait for condition or timeout

== SYNOPSIS

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

int nng_cv_until(nng_cv *cv, nng_time when);
----

== DESCRIPTION

The `nng_cv_until()` waits until either the condition variable _cv_ is 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()`], or the system clock (as tracked
by xref:nng_clock.3supp.adoc[`nng_clock()`]) reaches _when_.

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) {
        if (nng_cv_wait(cv) == NNG_ETIMEDOUT) {
            printf("Time out reached!\n");
            break;
        }
    }
    // condition_true is true
    nng_mtx_unlock(m);
----

.Example 2: Signaling the condition
[source, c]
----
    nng_mtx_lock(m);
    condition_true = true;
    nng_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_wait.3supp.adoc[nng_cv_wait(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)]