<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.5"/>
<title>open-vm-tools 9.4.0: Threading</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td style="padding-left: 0.5em;">
<div id="projectname">open-vm-tools 9.4.0
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.5 -->
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
<li><a href="annotated.html"><span>Data Structures</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
</ul>
</div>
</div><!-- top -->
<div class="header">
<div class="summary">
<a href="#nested-classes">Data Structures</a> |
<a href="#define-members">Macros</a> |
<a href="#typedef-members">Typedefs</a> |
<a href="#func-members">Functions</a> </div>
<div class="headertitle">
<div class="title">Threading</div> </div>
</div><!--header-->
<div class="contents">
<p>Thread Pooling and Monitoring.
<a href="#details">More...</a></p>
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="nested-classes"></a>
Data Structures</h2></td></tr>
<tr class="memitem:"><td class="memItemLeft" align="right" valign="top">struct  </td><td class="memItemRight" valign="bottom"><a class="el" href="structToolsCorePool.html">ToolsCorePool</a></td></tr>
<tr class="memdesc:"><td class="mdescLeft"> </td><td class="mdescRight">Public interface of the shared thread pool. <a href="structToolsCorePool.html#details">More...</a><br/></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2"> </td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="define-members"></a>
Macros</h2></td></tr>
<tr class="memitem:ga59a8568a7f0d87544ed0dc3cde743eed"><td class="memItemLeft" align="right" valign="top"><a class="anchor" id="ga59a8568a7f0d87544ed0dc3cde743eed"></a>
#define </td><td class="memItemRight" valign="bottom"><b>TOOLS_CORE_PROP_TPOOL</b>   "tcs_prop_thread_pool"</td></tr>
<tr class="separator:ga59a8568a7f0d87544ed0dc3cde743eed"><td class="memSeparator" colspan="2"> </td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="typedef-members"></a>
Typedefs</h2></td></tr>
<tr class="memitem:ga0896f3dc59232c168a431e835e7229ef"><td class="memItemLeft" align="right" valign="top">typedef void(* </td><td class="memItemRight" valign="bottom"><a class="el" href="group__vmtools__threads.html#ga0896f3dc59232c168a431e835e7229ef">ToolsCorePoolCb</a> )(<a class="el" href="structToolsAppCtx.html">ToolsAppCtx</a> *ctx, gpointer data)</td></tr>
<tr class="separator:ga0896f3dc59232c168a431e835e7229ef"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:gaaaa983561dc51500105b231613fe63d9"><td class="memItemLeft" align="right" valign="top">typedef struct <a class="el" href="structToolsCorePool.html">ToolsCorePool</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="group__vmtools__threads.html#gaaaa983561dc51500105b231613fe63d9">ToolsCorePool</a></td></tr>
<tr class="memdesc:gaaaa983561dc51500105b231613fe63d9"><td class="mdescLeft"> </td><td class="mdescRight">Public interface of the shared thread pool. <a href="#gaaaa983561dc51500105b231613fe63d9">More...</a><br/></td></tr>
<tr class="separator:gaaaa983561dc51500105b231613fe63d9"><td class="memSeparator" colspan="2"> </td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="func-members"></a>
Functions</h2></td></tr>
<tr class="memitem:gac715e0f8fd6527c369c634873000d23b"><td class="memItemLeft" align="right" valign="top">G_INLINE_FUNC <a class="el" href="structToolsCorePool.html">ToolsCorePool</a> * </td><td class="memItemRight" valign="bottom"><a class="el" href="group__vmtools__threads.html#gac715e0f8fd6527c369c634873000d23b">ToolsCorePool_GetPool</a> (<a class="el" href="structToolsAppCtx.html">ToolsAppCtx</a> *ctx)</td></tr>
<tr class="memdesc:gac715e0f8fd6527c369c634873000d23b"><td class="mdescLeft"> </td><td class="mdescRight">Returns the thread pool instance for the service. <a href="#gac715e0f8fd6527c369c634873000d23b">More...</a><br/></td></tr>
<tr class="separator:gac715e0f8fd6527c369c634873000d23b"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:ga813481657b59433baed593d8a7ff62e7"><td class="memItemLeft" align="right" valign="top">G_INLINE_FUNC guint </td><td class="memItemRight" valign="bottom"><a class="el" href="group__vmtools__threads.html#ga813481657b59433baed593d8a7ff62e7">ToolsCorePool_SubmitTask</a> (<a class="el" href="structToolsAppCtx.html">ToolsAppCtx</a> *ctx, <a class="el" href="group__vmtools__threads.html#ga0896f3dc59232c168a431e835e7229ef">ToolsCorePoolCb</a> cb, gpointer data, GDestroyNotify dtor)</td></tr>
<tr class="memdesc:ga813481657b59433baed593d8a7ff62e7"><td class="mdescLeft"> </td><td class="mdescRight">Submits a task for execution in the thread pool. <a href="#ga813481657b59433baed593d8a7ff62e7">More...</a><br/></td></tr>
<tr class="separator:ga813481657b59433baed593d8a7ff62e7"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:ga947496fbfc2cf6a1e8afd24d125c18bc"><td class="memItemLeft" align="right" valign="top">G_INLINE_FUNC void </td><td class="memItemRight" valign="bottom"><a class="el" href="group__vmtools__threads.html#ga947496fbfc2cf6a1e8afd24d125c18bc">ToolsCorePool_CancelTask</a> (<a class="el" href="structToolsAppCtx.html">ToolsAppCtx</a> *ctx, guint taskId)</td></tr>
<tr class="memdesc:ga947496fbfc2cf6a1e8afd24d125c18bc"><td class="mdescLeft"> </td><td class="mdescRight">Cancels a task previously submitted to the pool. <a href="#ga947496fbfc2cf6a1e8afd24d125c18bc">More...</a><br/></td></tr>
<tr class="separator:ga947496fbfc2cf6a1e8afd24d125c18bc"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:ga7f78bcaad21c82ddb8df50384564ddb0"><td class="memItemLeft" align="right" valign="top">G_INLINE_FUNC gboolean </td><td class="memItemRight" valign="bottom"><a class="el" href="group__vmtools__threads.html#ga7f78bcaad21c82ddb8df50384564ddb0">ToolsCorePool_StartThread</a> (<a class="el" href="structToolsAppCtx.html">ToolsAppCtx</a> *ctx, <a class="el" href="group__vmtools__threads.html#ga0896f3dc59232c168a431e835e7229ef">ToolsCorePoolCb</a> cb, <a class="el" href="group__vmtools__threads.html#ga0896f3dc59232c168a431e835e7229ef">ToolsCorePoolCb</a> interrupt, gpointer data, GDestroyNotify dtor)</td></tr>
<tr class="memdesc:ga7f78bcaad21c82ddb8df50384564ddb0"><td class="mdescLeft"> </td><td class="mdescRight">Starts a task on its own thread. <a href="#ga7f78bcaad21c82ddb8df50384564ddb0">More...</a><br/></td></tr>
<tr class="separator:ga7f78bcaad21c82ddb8df50384564ddb0"><td class="memSeparator" colspan="2"> </td></tr>
</table>
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
<p>Thread Pooling and Monitoring. </p>
<p>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.</p>
<p>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.</p>
<p>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. </p>
<h2 class="groupheader">Typedef Documentation</h2>
<a class="anchor" id="gaaaa983561dc51500105b231613fe63d9"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">typedef struct <a class="el" href="structToolsCorePool.html">ToolsCorePool</a> <a class="el" href="structToolsCorePool.html">ToolsCorePool</a></td>
</tr>
</table>
</div><div class="memdoc">
<p>Public interface of the shared thread pool. </p>
<p>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. </p>
</div>
</div>
<a class="anchor" id="ga0896f3dc59232c168a431e835e7229ef"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">typedef void(* ToolsCorePoolCb)(<a class="el" href="structToolsAppCtx.html">ToolsAppCtx</a> *ctx, gpointer data)</td>
</tr>
</table>
</div><div class="memdoc">
<p>Type of callback function used to register tasks with the pool. </p>
</div>
</div>
<h2 class="groupheader">Function Documentation</h2>
<a class="anchor" id="ga947496fbfc2cf6a1e8afd24d125c18bc"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">G_INLINE_FUNC void ToolsCorePool_CancelTask </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structToolsAppCtx.html">ToolsAppCtx</a> * </td>
<td class="paramname"><em>ctx</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">guint </td>
<td class="paramname"><em>taskId</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Cancels a task previously submitted to the pool. </p>
<p>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.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">ctx</td><td>Application context. </td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">taskId</td><td>Task ID returned by <a class="el" href="group__vmtools__threads.html#ga813481657b59433baed593d8a7ff62e7" title="Submits a task for execution in the thread pool. ">ToolsCorePool_SubmitTask()</a>. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a class="anchor" id="gac715e0f8fd6527c369c634873000d23b"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">G_INLINE_FUNC <a class="el" href="structToolsCorePool.html">ToolsCorePool</a>* ToolsCorePool_GetPool </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structToolsAppCtx.html">ToolsAppCtx</a> * </td>
<td class="paramname"><em>ctx</em></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Returns the thread pool instance for the service. </p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">ctx</td><td>Application context.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>The thread pool instance, or NULL if it's not available. </dd></dl>
</div>
</div>
<a class="anchor" id="ga7f78bcaad21c82ddb8df50384564ddb0"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">G_INLINE_FUNC gboolean ToolsCorePool_StartThread </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structToolsAppCtx.html">ToolsAppCtx</a> * </td>
<td class="paramname"><em>ctx</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="group__vmtools__threads.html#ga0896f3dc59232c168a431e835e7229ef">ToolsCorePoolCb</a> </td>
<td class="paramname"><em>cb</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="group__vmtools__threads.html#ga0896f3dc59232c168a431e835e7229ef">ToolsCorePoolCb</a> </td>
<td class="paramname"><em>interrupt</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">gpointer </td>
<td class="paramname"><em>data</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">GDestroyNotify </td>
<td class="paramname"><em>dtor</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Starts a task on its own thread. </p>
<p>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.</p>
<p>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.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">ctx</td><td>Application context. </td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">cb</td><td>Function that implements the task to execute. </td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">interrupt</td><td>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. </td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">data</td><td>Opaque data for both task callback and interrupt functions. </td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">dtor</td><td>Destructor for the task data.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>TRUE iff thread was successfully started. </dd></dl>
</div>
</div>
<a class="anchor" id="ga813481657b59433baed593d8a7ff62e7"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">G_INLINE_FUNC guint ToolsCorePool_SubmitTask </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structToolsAppCtx.html">ToolsAppCtx</a> * </td>
<td class="paramname"><em>ctx</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="group__vmtools__threads.html#ga0896f3dc59232c168a431e835e7229ef">ToolsCorePoolCb</a> </td>
<td class="paramname"><em>cb</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">gpointer </td>
<td class="paramname"><em>data</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">GDestroyNotify </td>
<td class="paramname"><em>dtor</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Submits a task for execution in the thread pool. </p>
<p>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.</p>
<p>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.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">ctx</td><td>Application context. </td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">cb</td><td>Function to execute the task. </td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">data</td><td>Opaque data for the task. </td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">dtor</td><td>Destructor for the task data.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>An identifier for the task, or 0 on error. </dd></dl>
</div>
</div>
</div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated on Wed Nov 13 2013 17:04:41 for open-vm-tools 9.4.0 by  <a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.5
</small></address>
</body>
</html>
