= nng_cv_until(3supp)
|
//
|
// Copyright 2021 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]
|
----
|
|
expire = nng_clock() + 1000; // 1 second in the future
|
nng_mtx_lock(m); // assume cv was allocated using m
|
while (!condition_true) {
|
if (nng_cv_until(cv, expire) == 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)]
|
