Group PJ_BARRIER_SEC

group PJ_BARRIER_SEC

This module provides abstraction to pj_barrier_t - synchronization barrier. It allows threads to block until all participating threads have reached the barrier, ensuring synchronization at specific points in execution. pj_barrier_t provides a barrier mechanism for synchronizing threads in a multithreaded application, similar to the POSIX pthread_barrier_wait or Windows EnterSynchronizationBarrier.

Enums

enum pj_barrier_flags

Flags that control the behavior of the barrier. Only supported on Windows platform starting from Windows 8. Otherwise, the flags are ignored.

Values:

enumerator PJ_BARRIER_FLAGS_BLOCK_ONLY

Specifies that the thread entering the barrier should block immediately until the last thread enters the barrier.

enumerator PJ_BARRIER_FLAGS_SPIN_ONLY

Specifies that the thread entering the barrier should spin until the last thread enters the barrier, even if the spinning thread exceeds the barrier’s maximum spin count.

enumerator PJ_BARRIER_FLAGS_NO_DELETE

Specifies that the function can skip the work required to ensure that it is safe to delete the barrier, which can improve performance. All threads that enter this barrier must specify the flag; otherwise, the flag is ignored. This flag should be used only if the barrier will never be deleted. “Never” means “when some thread is waiting on this barrier”.

Functions

pj_status_t pj_barrier_create(pj_pool_t *pool, unsigned thread_count, pj_barrier_t **p_barrier)

Create a barrier object. pj_barrier_create() creates a barrier object that can be used to synchronize threads. The barrier object is initialized with a thread count that specifies the number of threads that must call pj_barrier_wait() before any are allowed to proceed.

Warning

The behavior of the barrier is undefined if more threads than thread_count arrive at the barrier.

Parameters:

  • pool – The pool to allocate the barrier object.

  • thread_count – The number of threads that must call pj_barrier_wait() before any are allowed to proceed.

  • p_barrier – Pointer to hold the barrier object upon return.

Returns:

PJ_SUCCESS on success, or the error code.

pj_status_t pj_barrier_destroy(pj_barrier_t *barrier)

Destroy a barrier object. pj_barrier_destroy() destroys a barrier object and releases any resources associated with the barrier.

Parameters:

barrier – The barrier to destroy.

Returns:

PJ_SUCCESS on success, or the error code.

pj_int32_t pj_barrier_wait(pj_barrier_t *barrier, pj_uint32_t flags)

Wait for all threads to reach the barrier. pj_barrier_wait() allows threads to block until all participating threads have reached the barrier, ensuring synchronization at specific points in execution. It provides a barrier mechanism for synchronizing threads in a multithreaded application, similar to the POSIX pthread_barrier_wait or Windows EnterSynchronizationBarrier.

Warning

The behavior of the barrier is undefined if more threads arrive at the barrier than the thread_count specified when the barrier was created.

Parameters:

  • barrier – The barrier to wait on.

  • flags – Flags that control the behavior of the barrier (combination of pj_barrier_flags), default 0.

Returns:

Returns PJ_TRUE for a single (arbitrary) thread synchronized at the barrier and PJ_FALSE for each of the other threads. Otherwise, an error number shall be returned to indicate the error.