open-vm-tools 2015.01.29
Data Structures | Macros | Typedefs | Functions
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 ToolsCorePoolToolsCorePool_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

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.

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

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

Function Documentation

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]ctxApplication context.
[in]taskIdTask ID returned by ToolsCorePool_SubmitTask().
G_INLINE_FUNC ToolsCorePool* ToolsCorePool_GetPool ( ToolsAppCtx ctx)

Returns the thread pool instance for the service.

Parameters
[in]ctxApplication context.
Returns
The thread pool instance, or NULL if it's not available.
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]ctxApplication context.
[in]cbFunction that implements the task to execute.
[in]interruptA 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]dataOpaque data for both task callback and interrupt functions.
[in]dtorDestructor for the task data.
Returns
TRUE iff thread was successfully started.
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]ctxApplication context.
[in]cbFunction to execute the task.
[in]dataOpaque data for the task.
[in]dtorDestructor for the task data.
Returns
An identifier for the task, or 0 on error.