Thread Barrier

Overview

The XWOS thread barrier is a synchronization mechanism used to coordinate parallel work among multiple threads.

When creating a thread barrier, you specify how many thread slots it has. When a thread reaches the thread barrier, it will block and wait until the specified number of threads have all reached the barrier, at which point all threads are awakened simultaneously.

Thread Barrier Object and Object Descriptor

The thread barrier object is a derived class of XWOS Object struct xwos_object. Similarly, thread barrier objects also use the thread barrier object descriptor xwos_br_d to solve the problems of validity and identity legitimacy.

The thread barrier object descriptor is composed of a pointer to the thread barrier object and a tag:

typedef struct {
        struct xwos_br * br; /**< Pointer to the thread barrier object */
        xwsq_t tik; /**< Tag */
} xwos_br_d;

When referencing an object through the object descriptor, first check the value of obj->magic to see if it is 0x58574F53U, which confirms that the pointer obj points to a valid XWOS object. Then compare the tags obj->tik and tik to see if they are equal, which confirms the object’s identity. Since the object’s tik is globally unique, when the object is released, its tik will be destructed to 0 by the destructor. When the memory address is reconstructed into a new object, its tik will definitely differ from the tik in the object descriptor.

Thread Barrier Initialization, Destruction and Dynamic Creation, Deletion

Static Initialization and Destruction

• Static initialization: xwos_br_init()
  • Static means the user predefines thread structure objects, which are allocated memory by the compiler at compile time.
• Destroy statically initialized thread barrier: xwos_br_fini()

Dynamic Creation and Deletion

• Dynamic creation: xwos_br_create()
  • Dynamic means the program allocates memory through memory allocation functions at runtime and constructs the object on the allocated memory.
• Delete dynamically created thread barrier: xwos_br_delete()

Synchronizing Threads via Thread Barrier

• xwos_br_wait(): Wait for all threads to arrive at the barrier, can only be used in thread context
• xwos_br_wait_to(): Timed wait for all threads to arrive at the barrier, can only be used in thread context

Binding and Unbinding Signal Selector

The thread barrier can be bound to a signal selector via xwos_br_bind(). When the specified number of threads arrive at the thread barrier, the thread barrier sends a select signal to the signal selector. At this point, the signal selector wakes up the waiting thread.

A bound thread barrier can be unbound via xwos_br_unbind().

Thread Barrier Object Lifecycle Management

The base class of the thread barrier object is XWOS Object struct xwos_object. The thread barrier object also has two sets of lifecycle management CAPI:

• Access lifecycle management CAPI using object pointer: requires ensuring that the object is definitely valid when calling the CAPI, and there is no case of released-then-reallocated as another object.

  • xwos_br_grab(): Increase reference count.
  • xwos_br_put(): Decrease reference count. When the reference count drops to 0, the garbage collection function is called to release the object.

• Access lifecycle management CAPI using object descriptor: used when the user cannot guarantee that the object is definitely valid or cannot guarantee that the object has not become another object.

  • xwos_br_acquire(): Determine that the object is valid and legitimate through the object descriptor, then increase the reference count.
  • xwos_br_release(): Determine that the object is valid and legitimate through the object descriptor, then decrease the reference count. When the reference count drops to 0, the garbage collection function is called to release the object.

API Reference

• Header file <xwos/osal/sync/br.h>