Threading

Thread Pooling and Monitoring. More...

## Data Structures

struct | ToolsCorePool
| Public interface of the shared thread pool. More...

## Macros

#define | TOOLS_CORE_PROP_TPOOL "tcs_prop_thread_pool"

## Typedefs

typedef void(* | ToolsCorePoolCb) (ToolsAppCtx *ctx, gpointer data)
typedef struct ToolsCorePool | ToolsCorePool
| Public interface of the shared thread pool. More...

## Functions

G_INLINE_FUNC ToolsCorePool * | ToolsCorePool_GetPool (ToolsAppCtx *ctx)
| Returns the thread pool instance for the service. More...
G_INLINE_FUNC guint | ToolsCorePool_SubmitTask (ToolsAppCtx *ctx, ToolsCorePoolCb cb, gpointer data, GDestroyNotify dtor)
| Submits a task for execution in the thread pool. More...
G_INLINE_FUNC void | ToolsCorePool_CancelTask (ToolsAppCtx *ctx, guint taskId)
| Cancels a task previously submitted to the pool. More...
G_INLINE_FUNC gboolean | ToolsCorePool_StartThread (ToolsAppCtx *ctx, ToolsCorePoolCb cb, ToolsCorePoolCb interrupt, gpointer data, GDestroyNotify dtor)
| Starts a task on its own thread. More...

## Detailed Description

Thread Pooling and Monitoring.

vmtoolsd provides a worker thread pool for use by plugins. This pool is shared among all plugins, and is configurable from the Tools config file. Plugins can submit tasks to the thread pool by using one of the inline functions declared in this header.

The thread pool is a shared resource, so code whose execution time may be very long might want to, instead, create a dedicated thread for execution. The shared thread pool also provides a facility to more easily do that, with the lifecycle of the new thread managed by the thread pool so that it is properly notified of service shutdown.

Finally, depending on the configuration, the shared thread pool might not be a thread pool at all: if the configuration has disabled threading, tasks destined to the shared thread pool will be executed on the main service thread.

## Typedef Documentation

## ToolsCorePool

typedef struct ToolsCorePool ToolsCorePool

Public interface of the shared thread pool.

This struct is published in the service's TOOLS_CORE_PROP_TPOOL property, and contains function pointers to the internal implementation of the thread pool's functions. In general, applications may prefer to use the inline functions provided below instead, since they take care of some of the boilerplate code.

## ToolsCorePoolCb

typedef void(* ToolsCorePoolCb) (ToolsAppCtx *ctx, gpointer data)

Type of callback function used to register tasks with the pool.

## Function Documentation

## ToolsCorePool_CancelTask()

G_INLINE_FUNC void ToolsCorePool_CancelTask | ( | ToolsAppCtx * | ctx,
|  | guint | taskId
| ) |  |

Cancels a task previously submitted to the pool.

If the task is currently being executed, this function does nothing. Otherwise, the task is removed from the task queue, and its destructor (if any) is called.

Parameters

  [in] | ctx | Application context.
  [in] | taskId | Task ID returned by ToolsCorePool_SubmitTask().

## ToolsCorePool_GetPool()

G_INLINE_FUNC ToolsCorePool* ToolsCorePool_GetPool | ( | ToolsAppCtx * | ctx | ) |

Returns the thread pool instance for the service.

Parameters

  [in] | ctx | Application context.

Returns
  The thread pool instance, or NULL if it's not available.

## ToolsCorePool_StartThread()

G_INLINE_FUNC gboolean ToolsCorePool_StartThread | ( | ToolsAppCtx * | ctx,
|  | ToolsCorePoolCb | cb,
|  | ToolsCorePoolCb | interrupt,
|  | gpointer | data,
|  | GDestroyNotify | dtor
| ) |  |

Starts a task on its own thread.

This function will run a task on a dedicated thread that is not part of the shared thread pool. The thread will be managed by the thread pool, so that it's properly cleaned up when the service is shutting down.

Threads started by this function cannot be stopped by using the cancel function. Instead, if the application itself wants to stop the thread, it should call the interrupt function it provided to the thread pool, or use some other method of communicating with the thread.

Parameters

  [in] | ctx | Application context.
  [in] | cb | Function that implements the task to execute.
  [in] | interrupt | A function that will request the task to be interrupted. This will be called when the pool needs to stop all managed threads (e.g. during service shutdown). The task should stop what it's doing and end the thread soon after this callback is fired.
  [in] | data | Opaque data for both task callback and interrupt functions.
  [in] | dtor | Destructor for the task data.

Returns
  TRUE iff thread was successfully started.

## ToolsCorePool_SubmitTask()

G_INLINE_FUNC guint ToolsCorePool_SubmitTask | ( | ToolsAppCtx * | ctx,
|  | ToolsCorePoolCb | cb,
|  | gpointer | data,
|  | GDestroyNotify | dtor
| ) |  |

Submits a task for execution in the thread pool.

The task is queued in the thread pool and will be executed as soon as a worker thread is available. If the thread pool is disabled, the task will be executed on the main service thread as soon as the main loop is idle.

The task data's destructor will be called after the task finishes executing, or in case the thread pool is destroyed before the task is executed.

Parameters

  [in] | ctx | Application context.
  [in] | cb | Function to execute the task.
  [in] | data | Opaque data for the task.
  [in] | dtor | Destructor for the task data.

Returns
  An identifier for the task, or 0 on error.