<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html><head><meta name="robots" content="noindex">
<meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
<!-- THIS FILE IS AUTOMATICALLY GENERATED FROM THE GLOBUS SOURCE CODE
DO NOT MODIFY.
-->
<title>Globus Reference Manual</title>
<link href="doxygen.css" rel="stylesheet" type="text/css">
<link href="tabs.css" rel="stylesheet" type="text/css">
</head>
<body>
<!-- Generated by Doxygen 1.8.1.1 -->
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
<li><a href="annotated.html"><span>Data Structures</span></a></li>
</ul>
</div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('group__globus__ftp__client__restart__plugin.html','');});
</script>
<div id="doc-content">
<div class="header">
<div class="summary">
<a href="#define-members">Macros</a> |
<a href="#func-members">Functions</a> </div>
<div class="headertitle">
<div class="title">Restart Plugin</div> </div>
<div class="ingroups"><a class="el" href="group__globus__ftp__client__plugins.html">Plugins</a></div></div><!--header-->
<div class="contents">
<div class="dynheader">
Collaboration diagram for Restart Plugin:</div>
<div class="dyncontent">
<center><table><tr><td><img src="group__globus__ftp__client__restart__plugin.png" border="0" alt="" usemap="#group____globus____ftp____client____restart____plugin"/>
<map name="group____globus____ftp____client____restart____plugin" id="group____globus____ftp____client____restart____plugin">
<area shape="rect" id="node1" href="group__globus__ftp__client__plugins.html" title="Plugin API." alt="" coords="6,5,71,32"/></map>
</td></tr></table></center>
</div>
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2><a name="define-members"></a>
Macros</h2></td></tr>
<tr class="memitem:ga65c8a2548f1e4f4b004fcc58fbf7f87e"><td class="memItemLeft" align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="group__globus__ftp__client__restart__plugin.html#ga65c8a2548f1e4f4b004fcc58fbf7f87e">GLOBUS_FTP_CLIENT_RESTART_PLUGIN_MODULE</a>   (&globus_i_ftp_client_restart_plugin_module)</td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2><a name="func-members"></a>
Functions</h2></td></tr>
<tr class="memitem:ga2cfaf89ff36efe17ee30906e03347fc2"><td class="memItemLeft" align="right" valign="top">globus_result_t </td><td class="memItemRight" valign="bottom"><a class="el" href="group__globus__ftp__client__restart__plugin.html#ga2cfaf89ff36efe17ee30906e03347fc2">globus_ftp_client_restart_plugin_init</a> (<a class="el" href="group__globus__ftp__client__plugins.html#gafd650bbeee4bf50b94275d89352697dc">globus_ftp_client_plugin_t</a> *plugin, int max_retries, globus_reltime_t *interval, globus_abstime_t *deadline)</td></tr>
<tr class="memitem:ga50051ce7d4bfcb484f92a7a3c7ac3974"><td class="memItemLeft" align="right" valign="top">globus_result_t </td><td class="memItemRight" valign="bottom"><a class="el" href="group__globus__ftp__client__restart__plugin.html#ga50051ce7d4bfcb484f92a7a3c7ac3974">globus_ftp_client_restart_plugin_destroy</a> (<a class="el" href="group__globus__ftp__client__plugins.html#gafd650bbeee4bf50b94275d89352697dc">globus_ftp_client_plugin_t</a> *plugin)</td></tr>
</table>
<hr/><a name="details" id="details"></a><h2>Detailed Description</h2>
<p>The restart plugin implements one scheme for providing reliability functionality for the FTP Client library. </p>
<p>Other plugins may be developed to provide other methods of reliability.</p>
<p>The specific functionality of this plugin is to restart any FTP operation when a fault occurs. The plugin's operation is parameterized to control how often and when to attempt to restart the operation.</p>
<p>This restart plugin will restart an FTP operation if a noticeable fault has occurred—a connection timing out, a failure by the server to process a command, a protocol error, an authentication error.</p>
<p>This plugin has three user-configurable parameters; these are the maximum number of retries to attempt, the interval to wait between retries, and the deadline after which no further retries will be attempted. These are set by initializing a restart plugin instance with the function <a class="el" href="group__globus__ftp__client__restart__plugin.html#ga2cfaf89ff36efe17ee30906e03347fc2" title="Initialize an instance of the GridFTP restart pluginThis function will initialize the plugin-specific...">globus_ftp_client_restart_plugin_init()</a>.</p>
<h2>Example Usage</h2>
<p>The following example illustrates a typical use of the restart plugin. In this case, we configure a plugin instance to restart the operation for up to an hour, using an exponential back-off between retries.</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include "globus_ftp_client.h"</span></div>
<div class="line"><span class="preprocessor">#include "globus_ftp_client_restart_plugin.h"</span></div>
<div class="line"><span class="preprocessor">#include "globus_time.h"</span></div>
<div class="line"></div>
<div class="line"><span class="keywordtype">int</span></div>
<div class="line">main(<span class="keywordtype">int</span> argc, <span class="keywordtype">char</span> *argv[])</div>
<div class="line">{</div>
<div class="line"> <a class="code" href="group__globus__ftp__client__plugins.html#gafd650bbeee4bf50b94275d89352697dc" title="FTP Client pluginAn FTP Client plugin is used to add restart, monitoring, and performance tuning oper...">globus_ftp_client_plugin_t</a> restart_plugin;</div>
<div class="line"> <a class="code" href="group__globus__ftp__client__handleattr.html#gab4a1b9fd7b91ba74a5beb576ac3e307d" title="Handle Attributes.">globus_ftp_client_handleattr_t</a> handleattr;</div>
<div class="line"> <a class="code" href="group__globus__ftp__client__handle.html#ga9d8a98c88d529ab539c2fedee545f172" title="FTP Client Handle.">globus_ftp_client_handle_t</a> handle;</div>
<div class="line"> globus_abstime_t deadline;</div>
<div class="line"></div>
<div class="line"> globus_module_activate(<a class="code" href="group__globus__ftp__client__activation.html#gafad292f70aeba0451e27a6c1cdf5a831" title="Module descriptor.">GLOBUS_FTP_CLIENT_MODULE</a>);</div>
<div class="line"> globus_module_activate(<a class="code" href="group__globus__ftp__client__restart__plugin.html#ga65c8a2548f1e4f4b004fcc58fbf7f87e" title="Module descriptor.">GLOBUS_FTP_CLIENT_RESTART_PLUGIN_MODULE</a>);</div>
<div class="line"></div>
<div class="line"> <span class="comment">/* Set a deadline to be now + 1 hour */</span></div>
<div class="line"> GlobusAbstimeSet(deadline, 60 * 60, 0);</div>
<div class="line"></div>
<div class="line"> <span class="comment">/* initialize a plugin with this deadline */</span></div>
<div class="line"> <a class="code" href="group__globus__ftp__client__restart__plugin.html#ga2cfaf89ff36efe17ee30906e03347fc2" title="Initialize an instance of the GridFTP restart pluginThis function will initialize the plugin-specific...">globus_ftp_client_restart_plugin_init</a>(</div>
<div class="line"> &restart_plugin,</div>
<div class="line"> 0, <span class="comment">/* # retry limit (0 means don't limit) */</span></div>
<div class="line"> GLOBUS_NULL, <span class="comment">/* interval between retries--null means</span></div>
<div class="line"><span class="comment"> * exponential backoff</span></div>
<div class="line"><span class="comment"> */</span></div>
<div class="line"> &deadline);</div>
<div class="line"></div>
<div class="line"> <span class="comment">/* Set up our handle to use the new plugin */</span></div>
<div class="line"> <a class="code" href="group__globus__ftp__client__handleattr.html#ga55df5cb63ad06755dc9c707fb3b3197e" title="Initialize an FTP client handle attribute set.">globus_ftp_client_handleattr_init</a>(&handleattr);</div>
<div class="line"> <a class="code" href="group__globus__ftp__client__handleattr.html#ga77e24c2d75f9c847167179958fa28998" title="Add/Remove a plugin to a handle attribute set.">globus_ftp_client_handleattr_add_plugin</a>(&handleattr, &restart_plugin);</div>
<div class="line"> <a class="code" href="group__globus__ftp__client__handle.html#ga571af4a23e8985f9b36e2df3320fdd1d" title="Initialize a client FTP handle.">globus_ftp_client_handle_init</a>(&handle, &handleattr);</div>
<div class="line"></div>
<div class="line"> <span class="comment">/*</span></div>
<div class="line"><span class="comment"> * Now, if a fault occurs processing this get, the plugin will restart</span></div>
<div class="line"><span class="comment"> * it with an exponential back-off, and will bail if a fault occurs</span></div>
<div class="line"><span class="comment"> * after 1 hour of retrying</span></div>
<div class="line"><span class="comment"> */</span></div>
<div class="line"> <a class="code" href="group__globus__ftp__client__operations.html#ga6fe365dd2dfac6da159ff389e1f76a9b" title="Get a file from an FTP server.">globus_ftp_client_get</a>(&handle,</div>
<div class="line"> <span class="stringliteral">"ftp://ftp.globus.org/pub/globus/README"</span>,</div>
<div class="line"> GLOBUS_NULL,</div>
<div class="line"> GLOBUS_NULL,</div>
<div class="line"> callback_fn,</div>
<div class="line"> GLOBUS_NULL);</div>
<div class="line">}</div>
</div><!-- fragment --> <hr/><h2>Macro Definition Documentation</h2>
<a class="anchor" id="ga65c8a2548f1e4f4b004fcc58fbf7f87e"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">#define GLOBUS_FTP_CLIENT_RESTART_PLUGIN_MODULE   (&globus_i_ftp_client_restart_plugin_module)</td>
</tr>
</table>
</div><div class="memdoc">
<p>Module descriptor. </p>
</div>
</div>
<hr/><h2>Function Documentation</h2>
<a class="anchor" id="ga2cfaf89ff36efe17ee30906e03347fc2"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">globus_result_t globus_ftp_client_restart_plugin_init </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__globus__ftp__client__plugins.html#gafd650bbeee4bf50b94275d89352697dc">globus_ftp_client_plugin_t</a> * </td>
<td class="paramname"><em>plugin</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int </td>
<td class="paramname"><em>max_retries</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">globus_reltime_t * </td>
<td class="paramname"><em>interval</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">globus_abstime_t * </td>
<td class="paramname"><em>deadline</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Initialize an instance of the GridFTP restart pluginThis function will initialize the plugin-specific instance data for this plugin, and will make the plugin usable for ftp client handle attribute and handle creation. </p>
<dl class="params"><dt>Parameters:</dt><dd>
<table class="params">
<tr><td class="paramname">plugin</td><td>A pointer to an uninitialized plugin. The plugin will be configured as a restart plugin. </td></tr>
<tr><td class="paramname">max_retries</td><td>The maximum number of times to retry the operation before giving up on the transfer. If this value is less than or equal to 0, then the restart plugin will keep trying to restart the operation until it completes or the deadline is reached with an unsuccessful operation. </td></tr>
<tr><td class="paramname">interval</td><td>The interval to wait after a failures before retrying the transfer. If the interval is 0 seconds or GLOBUS_NULL, then an exponential backoff will be used. </td></tr>
<tr><td class="paramname">deadline</td><td>An absolute timeout. If the deadline is GLOBUS_NULL then the retry will never timeout.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns:</dt><dd>This function returns an error if<ul>
<li>plugin is null</li>
</ul>
</dd></dl>
<dl class="section see"><dt>See also:</dt><dd><a class="el" href="group__globus__ftp__client__restart__plugin.html#ga50051ce7d4bfcb484f92a7a3c7ac3974" title="Destroy an instance of the GridFTP restart pluginThis function will free all restart plugin-specific ...">globus_ftp_client_restart_plugin_destroy()</a>, <a class="el" href="group__globus__ftp__client__handleattr.html#ga77e24c2d75f9c847167179958fa28998" title="Add/Remove a plugin to a handle attribute set.">globus_ftp_client_handleattr_add_plugin()</a>, <a class="el" href="group__globus__ftp__client__handleattr.html#ga4ecb53ff8b985af31ad384f9ea5f31db" title="Add/Remove a plugin to a handle attribute set.">globus_ftp_client_handleattr_remove_plugin()</a>, <a class="el" href="group__globus__ftp__client__handle.html#ga571af4a23e8985f9b36e2df3320fdd1d" title="Initialize a client FTP handle.">globus_ftp_client_handle_init()</a> </dd></dl>
</div>
</div>
<a class="anchor" id="ga50051ce7d4bfcb484f92a7a3c7ac3974"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">globus_result_t globus_ftp_client_restart_plugin_destroy </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__globus__ftp__client__plugins.html#gafd650bbeee4bf50b94275d89352697dc">globus_ftp_client_plugin_t</a> * </td>
<td class="paramname"><em>plugin</em></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Destroy an instance of the GridFTP restart pluginThis function will free all restart plugin-specific instance data from this plugin, and will make the plugin unusable for further ftp handle creation. </p>
<p>Existing FTP client handles and handle attributes will not be affected by destroying a plugin associated with them, as a local copy of the plugin is made upon handle initialization.</p>
<dl class="params"><dt>Parameters:</dt><dd>
<table class="params">
<tr><td class="paramname">plugin</td><td>A pointer to a GridFTP restart plugin, previously initialized by calling <a class="el" href="group__globus__ftp__client__restart__plugin.html#ga2cfaf89ff36efe17ee30906e03347fc2" title="Initialize an instance of the GridFTP restart pluginThis function will initialize the plugin-specific...">globus_ftp_client_restart_plugin_init()</a></td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns:</dt><dd>This function returns an error if<ul>
<li>plugin is null</li>
<li>plugin is not a restart plugin</li>
</ul>
</dd></dl>
<dl class="section see"><dt>See also:</dt><dd><a class="el" href="group__globus__ftp__client__restart__plugin.html#ga2cfaf89ff36efe17ee30906e03347fc2" title="Initialize an instance of the GridFTP restart pluginThis function will initialize the plugin-specific...">globus_ftp_client_restart_plugin_init()</a>, <a class="el" href="group__globus__ftp__client__handleattr.html#ga77e24c2d75f9c847167179958fa28998" title="Add/Remove a plugin to a handle attribute set.">globus_ftp_client_handleattr_add_plugin()</a>, <a class="el" href="group__globus__ftp__client__handleattr.html#ga4ecb53ff8b985af31ad384f9ea5f31db" title="Add/Remove a plugin to a handle attribute set.">globus_ftp_client_handleattr_remove_plugin()</a>, <a class="el" href="group__globus__ftp__client__handle.html#ga571af4a23e8985f9b36e2df3320fdd1d" title="Initialize a client FTP handle.">globus_ftp_client_handle_init()</a> </dd></dl>
</div>
</div>
</div><!-- contents -->
</div><!-- doc-content -->
<hr>
<p align="center">
<a href="http://www.globus.org/toolkit/about.html" target="_top">about globus</a> |
<a href="http://www.globus.org/toolkit/" target="_top">globus toolkit</a> |
<a href="https://dev.globus.org/wiki/Welcome/" target="_top">dev.globus</a>
<br>
<br>
Comments? <a href="mailto:webmaster@globus.org">webmaster@globus.org</a>
</body>
</html>
