From 3db63c95b3b5cc8853fa6a3a19afe34a8ba20dd2 Mon Sep 17 00:00:00 2001 From: gdamore Date: Thu, 9 Oct 2025 00:01:13 +0000 Subject: deploy: d006acfdd44af4210e39f571fa32314bcd36bb40 --- ref/api/synch.html | 35 ++++++++++++++++++++--------------- 1 file changed, 20 insertions(+), 15 deletions(-) (limited to 'ref/api/synch.html') diff --git a/ref/api/synch.html b/ref/api/synch.html index 870bab9b..eb8672a2 100644 --- a/ref/api/synch.html +++ b/ref/api/synch.html @@ -245,32 +245,32 @@

Synchronization Primitives

In order to allow safely accessing shared state, or to allow coordination between -different threads, NNG provides synchronization primitives in the +different threads, NNG provides synchronization primitives in the form of mutual exclusion locks and condition variables.

Correct use of these primitives will be needed when accessing shared state from -threads, or from callback functions associated with asynchronous operations. +threads, or from callback functions associated with asynchronous operations. (The need to do this in callbacks is because the callback may be executed under a task thread other than the submitting thread.)

Mutual Exclusion Lock

typedef struct nng_mtx nng_mtx;

Mutual exclusion locks, or mutex locks, represented by the nng_mtx structure, -allow only a single thread to lock “own” the lock, acquired by nng_mtx_lock. +allow only a single thread to lock “own” the lock, acquired by nng_mtx_lock. Any other thread trying to acquire the same mutex will wait until the owner has released the mutex -by calling nng_mtx_unlock.

+by calling nng_mtx_unlock.

Creating a Mutex

int nng_mutx_alloc(nng_mt **mtxp);

A mutex can be created by allocating one with nng_mtx_lock. On success, a pointer to the mutex is returned through mtxp. This function can fail due to insufficient memory or resources, in which -case it will return NNG_ENOMEM. Otherwise it will succeed and return zero.

+case it will return NNG_ENOMEM. Otherwise it will succeed and return zero.

Destroying a Mutex

void nng_mtx_free(nng_mtx *mtx);

When no longer needed, a mutex can be deallocated and its resources returned to the caller, by calling nng_mtx_free. The mutex must not be locked -by any thread when calling this function.

+by any thread when calling this function.

Acquiring a Mutex

void nng_mtx_lock(nng_mtx *mtx);
@@ -288,7 +288,7 @@ If it does attempt to do so, the result will be a single party deadlock.

void nng_mtx_unlock(nng_mtx *mtx);

The nng_mtx_unlock function releases a mutex that the calling thread has previously -acquired with nng_mtx_lock.

+acquired with nng_mtx_lock.

@@ -301,7 +301,7 @@ that acquired the mutex to begin with.

typedef struct nng_cv nng_cv;

The nng_cv structure implements a condition variable, associated with the -the mutex mtx which was supplied when it was created.

+the mutex mtx which was supplied when it was created.

Condition variables provide for a way to wait on an arbitrary condition, and to be woken when the condition is signaled. The mutex is dropped while the caller is asleep, and reacquired atomically when the caller @@ -329,16 +329,16 @@ void nng_cv_wait(nng_cv *cv);

The nng_cv_until and nng_cv_wait functions put the caller to sleep until the condition variable cv is signaled, or (in the case of nng_cv_until), the specified time when -(as determined by nng_clock is reached.

+(as determined by nng_clock is reached.

While nng_cv_wait never fails and so has no return value, the nng_cv_until function can -return NNG_ETIMEDOUT if the time is reached before condition cv is signaled by -either nng_cv_wake or nng_cv_wake1.

+return NNG_ETIMEDOUT if the time is reached before condition cv is signaled by +either nng_cv_wake or nng_cv_wake1.

Signaling the Condition

void nng_cv_wake(nng_cv *cv);
 void nng_cv_wake1(nng_cv *cv);

The nng_cv_wake and nng_cv_wake1 functions wake threads waiting in -nng_cv_until or nng_cv_wait. +nng_cv_until or nng_cv_wait. The difference between these functions is that nng_cv_wake will wake every thread, whereas nng_cv_wake1 will wake up exactly one thread (which may be chosen randomly).

@@ -377,12 +377,17 @@ nng_cv_wake(cv); nng_mtx_unlock(m);

See Also

-

Threads, -Time, -Asynchronous I/O

+

Threads, +Time, +Asynchronous I/O

+ + -- cgit v1.2.3-70-g09d2