1
/*********************************************************
2
* Copyright (C) 2010 VMware, Inc. All rights reserved.
4
* This program is free software; you can redistribute it and/or modify it
5
* under the terms of the GNU Lesser General Public License as published
6
* by the Free Software Foundation version 2.1 and no later version.
8
* This program is distributed in the hope that it will be useful, but
9
* WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
10
* or FITNESS FOR A PARTICULAR PURPOSE. See the Lesser GNU General Public
11
* License for more details.
13
* You should have received a copy of the GNU Lesser General Public License
14
* along with this program; if not, write to the Free Software Foundation, Inc.,
15
* 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
17
*********************************************************/
19
#ifndef _THREADPOOL_H_
20
#define _THREADPOOL_H_
25
* Public interface for vmtoolsd's thread pool.
27
* vmtoolsd provides a worker thread pool for use by plugins. This pool is
28
* shared among all plugins, and is configurable from the Tools config file.
29
* Plugins can submit tasks to the thread pool by using one of the inline
30
* functions declared in this header.
32
* The thread pool is a shared resource, so code whose execution time may be
33
* very long might want to, instead, create a dedicated thread for execution.
34
* The shared thread pool also provides a facility to more easily do that,
35
* with the lifecycle of the new thread managed by the thread pool so that it
36
* is properly notified of service shutdown.
38
* Finally, depending on the configuration, the shared thread pool might not
39
* be a thread pool at all: if the configuration has disabled threading, tasks
40
* destined to the shared thread pool will be executed on the main service
44
#include <glib-object.h>
45
#include "vmware/tools/plugin.h"
47
#define TOOLS_CORE_PROP_TPOOL "tcs_prop_thread_pool"
49
/** Type of callback function used to register tasks with the pool. */
50
typedef void (*ToolsCorePoolCb)(ToolsAppCtx *ctx,
54
* @brief Public interface of the shared thread pool.
56
* This struct is published in the service's TOOLS_CORE_PROP_TPOOL property,
57
* and contains function pointers to the internal implementation of the
58
* thread pool's functions. In general, applications may prefer to use the
59
* inline functions provided below instead, since they take care of some of
60
* the boilerplate code.
62
typedef struct ToolsCorePool {
63
guint (*submit)(ToolsAppCtx *ctx,
67
void (*cancel)(guint id);
68
gboolean (*start)(ToolsAppCtx *ctx,
70
ToolsCorePoolCb interrupt,
77
*******************************************************************************
78
* ToolsCorePool_GetPool -- */ /**
80
* @brief Returns the thread pool instance for the service.
82
* @param[in] ctx Application context.
84
* @return The thread pool instance, or NULL if it's not available.
86
*******************************************************************************
89
G_INLINE_FUNC ToolsCorePool *
90
ToolsCorePool_GetPool(ToolsAppCtx *ctx)
92
ToolsCorePool *pool = NULL;
93
g_object_get(ctx->serviceObj, TOOLS_CORE_PROP_TPOOL, &pool, NULL);
99
*******************************************************************************
100
* ToolsCorePool_SubmitTask -- */ /**
102
* @brief Submits a task for execution in the thread pool.
104
* The task is queued in the thread pool and will be executed as soon as a
105
* worker thread is available. If the thread pool is disabled, the task will
106
* be executed on the main service thread as soon as the main loop is idle.
108
* The task data's destructor will be called after the task finishes executing,
109
* or in case the thread pool is destroyed before the task is executed.
111
* @param[in] ctx Application context.
112
* @param[in] cb Function to execute the task.
113
* @param[in] data Opaque data for the task.
114
* @param[in] dtor Destructor for the task data.
116
* @return An identifier for the task, or 0 on error.
118
*******************************************************************************
122
ToolsCorePool_SubmitTask(ToolsAppCtx *ctx,
127
ToolsCorePool *pool = ToolsCorePool_GetPool(ctx);
129
return pool->submit(ctx, cb, data, dtor);
136
*******************************************************************************
137
* ToolsCorePool_CancelTask -- */ /**
139
* @brief Cancels a task previously submitted to the pool.
141
* If the task is currently being executed, this function does nothing.
142
* Otherwise, the task is removed from the task queue, and its destructor
143
* (if any) is called.
145
* @param[in] ctx Application context.
146
* @param[in] taskId Task ID returned by ToolsCorePool_SubmitTask().
148
*******************************************************************************
152
ToolsCorePool_CancelTask(ToolsAppCtx *ctx,
155
ToolsCorePool *pool = ToolsCorePool_GetPool(ctx);
157
pool->cancel(taskId);
163
*******************************************************************************
164
* ToolsCorePool_StartThread -- */ /**
166
* @brief Starts a task on its own thread.
168
* This function will run a task on a dedicated thread that is not part of
169
* the shared thread pool. The thread will be managed by the thread pool, so
170
* that it's properly cleaned up when the service is shutting down.
172
* Threads started by this function cannot be stopped by using the cancel
173
* function. Instead, if the application itself wants to stop the thread, it
174
* should call the interrupt function it provided to the thread pool, or use
175
* some other method of communicating with the thread.
177
* @param[in] ctx Application context.
178
* @param[in] cb Function that implements the task to execute.
179
* @param[in] interrupt A function that will request the task to be
180
* interrupted. This will be called when the pool
181
* needs to stop all managed threads (e.g. during
182
* service shutdown). The task should stop what it's
183
* doing and end the thread soon after this callback
185
* @param[in] data Opaque data for both task callback and interrupt
187
* @param[in] dtor Destructor for the task data.
189
* @return TRUE iff thread was successfully started.
191
*******************************************************************************
194
G_INLINE_FUNC gboolean
195
ToolsCorePool_StartThread(ToolsAppCtx *ctx,
197
ToolsCorePoolCb interrupt,
201
ToolsCorePool *pool = ToolsCorePool_GetPool(ctx);
203
return pool->start(ctx, cb, interrupt, data, dtor);
209
#endif /* _THREADPOOL_H_ */
added
removed
lib/include/vmware/tools/threadPool.h
