Typedefs | Enumerations | Functions
workqueue.h File Reference
#include "lib/cc/torint.h"

Go to the source code of this file.


typedef struct replyqueue_s replyqueue_t
typedef struct threadpool_s threadpool_t
typedef struct workqueue_entry_s workqueue_entry_t
typedef enum workqueue_reply_t workqueue_reply_t
typedef enum workqueue_priority_t workqueue_priority_t


enum  workqueue_reply_t { WQ_RPL_REPLY = 0, WQ_RPL_ERROR = 1, WQ_RPL_SHUTDOWN = 2 }
enum  workqueue_priority_t { WQ_PRI_HIGH = 0, WQ_PRI_MED = 1, WQ_PRI_LOW = 2 }


workqueue_entry_tthreadpool_queue_work_priority (threadpool_t *pool, workqueue_priority_t prio, workqueue_reply_t(*fn)(void *, void *), void(*reply_fn)(void *), void *arg)
workqueue_entry_tthreadpool_queue_work (threadpool_t *pool, workqueue_reply_t(*fn)(void *, void *), void(*reply_fn)(void *), void *arg)
int threadpool_queue_update (threadpool_t *pool, void *(*dup_fn)(void *), workqueue_reply_t(*fn)(void *, void *), void(*free_fn)(void *), void *arg)
void * workqueue_entry_cancel (workqueue_entry_t *pending_work)
threadpool_tthreadpool_new (int n_threads, replyqueue_t *replyqueue, void *(*new_thread_state_fn)(void *), void(*free_thread_state_fn)(void *), void *arg)
replyqueue_tthreadpool_get_replyqueue (threadpool_t *tp)
replyqueue_treplyqueue_new (uint32_t alertsocks_flags)
void replyqueue_process (replyqueue_t *queue)
int threadpool_register_reply_event (threadpool_t *tp, void(*cb)(threadpool_t *tp))

Detailed Description

Header for workqueue.c.

Definition in file workqueue.h.

Typedef Documentation

◆ replyqueue_t

typedef struct replyqueue_s replyqueue_t

A replyqueue is used to tell the main thread about the outcome of work that we queued for the workers.

Definition at line 16 of file workqueue.h.

◆ threadpool_t

typedef struct threadpool_s threadpool_t

A thread-pool manages starting threads and passing work to them.

Definition at line 18 of file workqueue.h.

◆ workqueue_entry_t

A workqueue entry represents a request that has been passed to a thread pool.

Definition at line 21 of file workqueue.h.

◆ workqueue_priority_t

Possible priorities for work. Lower numeric values are more important.

◆ workqueue_reply_t

Possible return value from a work function:

Enumeration Type Documentation

◆ workqueue_priority_t

Possible priorities for work. Lower numeric values are more important.

Definition at line 31 of file workqueue.h.

◆ workqueue_reply_t

Possible return value from a work function:


indicates success


indicates fatal error

Definition at line 24 of file workqueue.h.

Function Documentation

◆ replyqueue_new()

replyqueue_t* replyqueue_new ( uint32_t  alertsocks_flags)

Allocate a new reply queue. Reply queues are used to pass results from worker threads to the main thread. Since the main thread is running an IO-centric event loop, it needs to get woken up with means other than a condition variable.

Definition at line 586 of file workqueue.c.

◆ replyqueue_process()

void replyqueue_process ( replyqueue_t queue)

Process all pending replies on a reply queue. The main thread should call this function every time the socket returned by replyqueue_get_socket() is readable.

Definition at line 647 of file workqueue.c.

Referenced by reply_event_cb().

◆ threadpool_get_replyqueue()

replyqueue_t* threadpool_get_replyqueue ( threadpool_t tp)

Return the reply queue associated with a given thread pool.

Definition at line 576 of file workqueue.c.

References threadpool_s::reply_queue.

◆ threadpool_new()

threadpool_t* threadpool_new ( int  n_threads,
replyqueue_t replyqueue,
void *(*)(void *)  new_thread_state_fn,
void(*)(void *)  free_thread_state_fn,
void *  arg 

Construct a new thread pool with n worker threads, configured to send their output to replyqueue. The threads' states will be constructed with the new_thread_state_fn call, receiving arg as its argument. When the threads close, they will call free_thread_state_fn on their states.

Definition at line 541 of file workqueue.c.

◆ threadpool_queue_update()

int threadpool_queue_update ( threadpool_t pool,
void *(*)(void *)  dup_fn,
workqueue_reply_t(*)(void *, void *)  fn,
void(*)(void *)  free_fn,
void *  arg 

Queue a copy of a work item for every thread in a pool. This can be used, for example, to tell the threads to update some parameter in their states.

Arguments are as for threadpool_queue_work, except that the arg value is passed to dup_fn once per each thread to make a copy of it.

UPDATE FUNCTIONS MUST BE IDEMPOTENT. We do not guarantee that every update will be run. If a new update is scheduled before the old update finishes running, then the new will replace the old in any threads that haven't run it yet.

Return 0 on success, -1 on failure.

Definition at line 437 of file workqueue.c.

References threadpool_s::free_update_arg_fn, threadpool_s::lock, threadpool_s::n_threads, tor_mutex_acquire(), and threadpool_s::update_args.

◆ threadpool_queue_work()

workqueue_entry_t* threadpool_queue_work ( threadpool_t pool,
workqueue_reply_t(*)(void *, void *)  fn,
void(*)(void *)  reply_fn,
void *  arg 

As threadpool_queue_work_priority(), but assumes WQ_PRI_HIGH

Definition at line 413 of file workqueue.c.

References threadpool_queue_work_priority().

◆ threadpool_queue_work_priority()

workqueue_entry_t* threadpool_queue_work_priority ( threadpool_t pool,
workqueue_priority_t  prio,
workqueue_reply_t(*)(void *, void *)  fn,
void(*)(void *)  reply_fn,
void *  arg 

Queue an item of work for a thread in a thread pool. The function fn will be run in a worker thread, and will receive as arguments the thread's state object, and the provided object arg. It must return one of WQ_RPL_REPLY, WQ_RPL_ERROR, or WQ_RPL_SHUTDOWN.

Regardless of its return value, the function reply_fn will later be run in the main thread when it invokes replyqueue_process(), and will receive as its argument the same arg object. It's the reply function's responsibility to free the work object.

On success, return a workqueue_entry_t object that can be passed to workqueue_entry_cancel(). On failure, return NULL. (Failure is not currently possible, but callers should check anyway.)

Items are executed in a loose priority order – each thread will usually take from the queued work with the highest prioirity, but will occasionally visit lower-priority queues to keep them from starving completely.

Note that because of priorities and thread behavior, work items may not be executed strictly in order.

Definition at line 386 of file workqueue.c.

References tor_assert().

Referenced by threadpool_queue_work().

◆ threadpool_register_reply_event()

int threadpool_register_reply_event ( threadpool_t tp,
void(*)(threadpool_t *tp)  cb 

Register the threadpool tp's reply queue with Tor's global libevent mainloop. If cb is provided, it is run after each time there is work to process from the reply queue. Return 0 on success, -1 on failure.

Definition at line 623 of file workqueue.c.

References threadpool_s::reply_event.

◆ workqueue_entry_cancel()

void* workqueue_entry_cancel ( workqueue_entry_t ent)

Cancel a workqueue_entry_t that has been returned from threadpool_queue_work.

You must not call this function on any work whose reply function has been executed in the main thread; that will cause undefined behavior (probably, a crash).

If the work is cancelled, this function return the argument passed to the work function. It is the caller's responsibility to free this storage.

This function will have no effect if the worker thread has already executed or begun to execute the work item. In that case, it will return NULL.

Definition at line 191 of file workqueue.c.

References tor_mutex_acquire(), and tor_mutex_release().

Referenced by cpuworker_cancel_circ_handshake().