BLI_task.h

Go to the documentation of this file.

/* SPDX-FileCopyrightText: 2023 Blender Authors
 *
 * SPDX-License-Identifier: GPL-2.0-or-later */
 
/* Use a define instead of `#pragma once` because of `bmesh_iterators_inline.hh` */
#ifndef __BLI_TASK_H__
#define __BLI_TASK_H__
 
#include <string.h> /* for memset() */
 
#include "BLI_threads.h"
#include "BLI_utildefines.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
struct BLI_mempool;
 
/* -------------------------------------------------------------------- */
void BLI_task_scheduler_init(void);
void BLI_task_scheduler_exit(void);
int BLI_task_scheduler_num_threads(void);
 
/* -------------------------------------------------------------------- */
typedef enum eTaskPriority {
  TASK_PRIORITY_LOW,
  TASK_PRIORITY_HIGH,
} eTaskPriority;
 
typedef struct TaskPool TaskPool;
typedef void (*TaskRunFunction)(TaskPool *__restrict pool, void *taskdata);
typedef void (*TaskFreeFunction)(TaskPool *__restrict pool, void *taskdata);
 
TaskPool *BLI_task_pool_create(void *userdata, eTaskPriority priority);
 
TaskPool *BLI_task_pool_create_background(void *userdata, eTaskPriority priority);
 
TaskPool *BLI_task_pool_create_background_serial(void *userdata, eTaskPriority priority);
 
TaskPool *BLI_task_pool_create_suspended(void *userdata, eTaskPriority priority);
 
TaskPool *BLI_task_pool_create_no_threads(void *userdata);
 
void BLI_task_pool_free(TaskPool *pool);
 
void BLI_task_pool_push(TaskPool *pool,
                        TaskRunFunction run,
                        void *taskdata,
                        bool free_taskdata,
                        TaskFreeFunction freedata);
 
void BLI_task_pool_work_and_wait(TaskPool *pool);
void BLI_task_pool_cancel(TaskPool *pool);
 
bool BLI_task_pool_current_canceled(TaskPool *pool);
 
void *BLI_task_pool_user_data(TaskPool *pool);
 
ThreadMutex *BLI_task_pool_user_mutex(TaskPool *pool);
 
/* -------------------------------------------------------------------- */
typedef struct TaskParallelTLS {
  void *userdata_chunk;
} TaskParallelTLS;
 
typedef void (*TaskParallelRangeFunc)(void *__restrict userdata,
                                      int iter,
                                      const TaskParallelTLS *__restrict tls);
 
typedef void (*TaskParallelInitFunc)(const void *__restrict userdata, void *__restrict chunk);
 
typedef void (*TaskParallelReduceFunc)(const void *__restrict userdata,
                                       void *__restrict chunk_join,
                                       void *__restrict chunk);
 
typedef void (*TaskParallelFreeFunc)(const void *__restrict userdata, void *__restrict chunk);
 
typedef struct TaskParallelSettings {
  /* Whether caller allows to do threading of the particular range.
   * Usually set by some equation, which forces threading off when threading
   * overhead becomes higher than speed benefit.
   * BLI_task_parallel_range() by itself will always use threading when range
   * is higher than a chunk size. As in, threading will always be performed.
   */
  bool use_threading;
  /* Each instance of looping chunks will get a copy of this data
   * (similar to OpenMP's firstprivate).
   */
  void *userdata_chunk;       /* Pointer to actual data. */
  size_t userdata_chunk_size; /* Size of that data. */
  /* Function called from calling thread once whole range have been
   * processed.
   */
  /* Function called to initialize user data chunk,
   * typically to allocate data, freed by `func_free`.
   */
  TaskParallelInitFunc func_init;
  /* Function called to join user data chunk into another, to reduce
   * the result to the original userdata_chunk memory.
   * The reduce functions should have no side effects, so that they
   * can be run on any thread. */
  TaskParallelReduceFunc func_reduce;
  /* Function called to free data created by TaskParallelRangeFunc. */
  TaskParallelFreeFunc func_free;
  /* Minimum allowed number of range iterators to be handled by a single
   * thread. This allows to achieve following:
   * - Reduce amount of threading overhead.
   * - Partially occupy thread pool with ranges which are computationally
   *   expensive, but which are smaller than amount of available threads.
   *   For example, it's possible to multi-thread [0 .. 64] range into 4
   *   thread which will be doing 16 iterators each.
   * This is a preferred way to tell scheduler when to start threading than
   * having a global use_threading switch based on just range size.
   */
  int min_iter_per_thread;
} TaskParallelSettings;
 
BLI_INLINE void BLI_parallel_range_settings_defaults(TaskParallelSettings *settings);
 
void BLI_task_parallel_range(int start,
                             int stop,
                             void *userdata,
                             TaskParallelRangeFunc func,
                             const TaskParallelSettings *settings);
 
typedef struct MempoolIterData MempoolIterData;
 
typedef void (*TaskParallelMempoolFunc)(void *userdata,
                                        MempoolIterData *iter,
                                        const TaskParallelTLS *__restrict tls);
void BLI_task_parallel_mempool(struct BLI_mempool *mempool,
                               void *userdata,
                               TaskParallelMempoolFunc func,
                               const TaskParallelSettings *settings);
 
BLI_INLINE void BLI_parallel_range_settings_defaults(TaskParallelSettings *settings)
{
  memset(settings, 0, sizeof(*settings));
  settings->use_threading = true;
  /* Use default heuristic to define actual chunk size. */
  settings->min_iter_per_thread = 0;
}
 
BLI_INLINE void BLI_parallel_mempool_settings_defaults(TaskParallelSettings *settings)
{
  memset(settings, 0, sizeof(*settings));
  settings->use_threading = true;
}
 
int BLI_task_parallel_thread_id(const TaskParallelTLS *tls);
 
/* -------------------------------------------------------------------- */
struct TaskGraph;
struct TaskNode;
 
typedef void (*TaskGraphNodeRunFunction)(void *__restrict task_data);
typedef void (*TaskGraphNodeFreeFunction)(void *task_data);
 
struct TaskGraph *BLI_task_graph_create(void);
void BLI_task_graph_work_and_wait(struct TaskGraph *task_graph);
void BLI_task_graph_free(struct TaskGraph *task_graph);
struct TaskNode *BLI_task_graph_node_create(struct TaskGraph *task_graph,
                                            TaskGraphNodeRunFunction run,
                                            void *user_data,
                                            TaskGraphNodeFreeFunction free_func);
bool BLI_task_graph_node_push_work(struct TaskNode *task_node);
void BLI_task_graph_edge_create(struct TaskNode *from_node, struct TaskNode *to_node);
 
/* -------------------------------------------------------------------- */
void BLI_task_isolate(void (*func)(void *userdata), void *userdata);
 
#ifdef __cplusplus
}
#endif
 
#endif