work-range.c

typedef struct {
  /**
   * Number of remaining unclaimed elements in the range.
   * Initialized to the total number of elements during work range initialization, decremented as threads claim elements for processing.
   * When the whole work range is processed, this element must equal 0.
   */
  uint64_t unclaimed;
  /**
   * Total number of elements in the range.
   * Initialized during work range initialization, and never changes after it.
   */
  uint64_t total;
} work_range_t;

/*
 * Initializes work range that can dynamically split between multiple threads.
 * The work range initially contains @a work_items elements numbered from 0 to (work_items - 1).
 * Multiple threads can call @ref request_work_items to claim up to specified number of elements from the range.
 *
 * @param[out] work_range_ptr  Pointer to the work_range_t structure to be initialized.
 * @param[in]  work_items      The total number of work items in the work range being created.
 */
void init_work_range(volatile work_range_t* work_range_ptr, uint64_t work_items);

typedef struct {
  uint64_t start;
  uint64_t count;
} work_items_t;

/**
 * Claims up to @a work_items elements from the work range.
 * Returns @ref work_items_t structure that contains index of the first element in the claimed range and the number of elements in the claimed range.
 * The returned number of elements never exceeds requested @a work_items. After the whole work range is processed, calls to this function return 0 elements.
 * 
 * @note This function is thread-safe and reentrant
 * 
 * @param[in, out] work_range_ptr  Pointer to the work range with the elements to claim. The work range is atomically updated as a result of this call.
 * @param[in]      work_items      The desired number of elements to claim.
 */
work_items_t request_work_items(volatile work_range_t* work_range_ptr, uint64_t work_items);