Globus Callback API. More...

Convenience Macros
#define	globus_callback_poll(a)
	Poll the global callback space. More...

#define	globus_poll_blocking()
	Blocking poll of the global callback space. More...

#define	globus_poll_nonblocking()
	Nonblocking poll of the global callback space. More...

#define	globus_poll()
	Nonblocking poll of the global callback space. More...

#define	globus_signal_poll()
	Wake up callback polling thread. More...

#define	globus_callback_register_oneshot(callback_handle,delay_time,callback_func,callback_user_arg)
	Register a oneshot function in the global callback space. More...

#define	globus_callback_register_periodic(callback_handle,delay_time,period,callback_func,callback_user_arg)
	Register a periodic function in the global callback space. More...

#define	globus_callback_register_signal_handler(signum,persist,callback_func,callback_user_arg)
	Register a signal handler in the global callback space. More...

Callback Prototypes
typedef void(*	globus_callback_func_t )(void *user_arg)
	Globus callback prototype. More...

Oneshot Callbacks
globus_result_t	globus_callback_space_register_oneshot (globus_callback_handle_t callback_handle, const globus_reltime_t delay_time, globus_callback_func_t callback_func, void *callback_user_arg, globus_callback_space_t space)
	Register a oneshot some delay from now. More...

Periodic Callbacks
globus_result_t	globus_callback_space_register_periodic (globus_callback_handle_t callback_handle, const globus_reltime_t delay_time, const globus_reltime_t period, globus_callback_func_t callback_func, void callback_user_arg, globus_callback_space_t space)
	Register a periodic callback. More...

globus_result_t	globus_callback_unregister (globus_callback_handle_t callback_handle, globus_callback_func_t unregister_callback, void unreg_arg, globus_bool_t active)
	Unregister a callback. More...

globus_result_t	globus_callback_adjust_oneshot (globus_callback_handle_t callback_handle, const globus_reltime_t *new_delay)
	Adjust the delay of a oneshot callback. More...

globus_result_t	globus_callback_adjust_period (globus_callback_handle_t callback_handle, const globus_reltime_t *new_period)
	Adjust the period of a periodic callback. More...

Callback Polling
void	globus_callback_space_poll (const globus_abstime_t *timestop, globus_callback_space_t space)
	Poll for ready callbacks. More...

void	globus_callback_signal_poll ()
	Signal the poll. More...

Miscellaneous
globus_bool_t	globus_callback_get_timeout (globus_reltime_t *time_left)
	Get the amount of time left in a callback. More...

globus_bool_t	globus_callback_has_time_expired ()
	See if there is remaining time in a callback. More...

globus_bool_t	globus_callback_was_restarted ()
	See if a callback has been restarted. More...

Detailed Description

Globus Callback API.

Macro Definition Documentation

#define globus_callback_poll ( a )

Poll the global callback space.

Specifies the global space for globus_callback_space_poll(). argument is the timeout

See Also: globus_callback_space_poll()

#define globus_callback_register_oneshot	(	callback_handle,
		delay_time,
		callback_func,
		callback_user_arg
	)

Register a oneshot function in the global callback space.

Specifies the global space for globus_callback_space_register_oneshot() all other arguments are the same as specified there.

See Also: globus_callback_space_register_oneshot()

#define globus_callback_register_periodic	(	callback_handle,
		delay_time,
		period,
		callback_func,
		callback_user_arg
	)

Register a periodic function in the global callback space.

Specifies the global space for globus_callback_space_register_periodic() all other arguments are the same as specified there.

See Also: globus_callback_space_register_periodic()

#define globus_callback_register_signal_handler	(	signum,
		persist,
		callback_func,
		callback_user_arg
	)

Register a signal handler in the global callback space.

Specifies the global space for globus_callback_space_register_signal_handler() all other arguments are the same as specified there.

See Also: globus_callback_space_register_signal_handler()

#define globus_poll ( )

Nonblocking poll of the global callback space.

Specifies that globus_callback_space_poll() should poll on the global space with an immediate timeout

See Also: globus_callback_space_poll()

#define globus_poll_blocking ( )

Blocking poll of the global callback space.

Specifies that globus_callback_space_poll() should poll on the global space with an infinite timeout

See Also: globus_callback_space_poll()

#define globus_poll_nonblocking ( )

Nonblocking poll of the global callback space.

Specifies that globus_callback_space_poll() should poll on the global space with an immediate timeout

See Also: globus_callback_space_poll()

#define globus_signal_poll ( )

Wake up callback polling thread.

Counterpart to globus_poll().

See Also: globus_callback_signal_poll()

Typedef Documentation

typedef void(* globus_callback_func_t)(void *user_arg)

Globus callback prototype.

This is the signature of the function registered with the globus_callback_register_* calls.

If this is a periodic callback, it is guaranteed that the call canNOT be reentered unless globus_thread_blocking_space_will_block() is called (explicitly, or implicitly via globus_cond_wait()). Also, if globus_callback_unregister() is called to cancel this periodic from within this callback, it is guaranteed that the callback will NOT be requeued again

If the function will block at all, the user should call globus_callback_get_timeout() to see how long this function can safely block or call globus_thread_blocking_space_will_block()

Parameters

user_arg The user argument registered with this callback

See Also: globus_callback_space_register_oneshot(); globus_callback_space_register_periodic(); globus_thread_blocking_space_will_block(); globus_callback_get_timeout()

Function Documentation

globus_result_t globus_callback_adjust_oneshot	(	globus_callback_handle_t	callback_handle,
		const globus_reltime_t *	new_delay
	)

Adjust the delay of a oneshot callback.

This function allows a user to adjust the delay of a previously registered callback. It is safe to call this within or outside of the callback that is being modified.

Note if the oneshot has already been fired, this function will still return GLOBUS_SUCCESS, but won't affect anything.

Parameters

callback_handle	the handle received from a globus_callback_space_register_oneshot() call
new_delay	The new delay from now. If NULL, then callback will be fired as soon as possible.

Returns

GLOBUS_CALLBACK_ERROR_INVALID_CALLBACK_HANDLE
GLOBUS_CALLBACK_ERROR_ALREADY_CANCELED
GLOBUS_SUCCESS

See Also: globus_callback_space_register_periodic()

globus_result_t globus_callback_adjust_period	(	globus_callback_handle_t	callback_handle,
		const globus_reltime_t *	new_period
	)

Adjust the period of a periodic callback.

This function allows a user to adjust the period of a previously registered callback. It is safe to call this within or outside of the callback that is being modified.

This func also allows a user to effectively 'suspend' a periodic callback until another time by passing a period of NULL. The callback can later be resumed by passing in a new period.

Note that the callback will not be fired sooner than 'new_period' from now. A 'suspended' callback must still be unregistered to free its resources.

Parameters

callback_handle	the handle received from a globus_callback_space_register_periodic() call
new_period	The new period. If NULL or globus_i_reltime_infinity, then callback will be 'suspended' as soon as the last running instance of it returns.

Returns

GLOBUS_CALLBACK_ERROR_INVALID_CALLBACK_HANDLE
GLOBUS_CALLBACK_ERROR_ALREADY_CANCELED
GLOBUS_SUCCESS

See Also: globus_callback_space_register_periodic()

globus_bool_t globus_callback_get_timeout ( globus_reltime_t * time_left )

Get the amount of time left in a callback.

This function retrieves the remaining time a callback is allowed to run. If a callback has already timed out, time_left will be set to zero and GLOBUS_TRUE returned. This function is intended to be called within a callback's stack, but is harmless to call anywhere (will return GLOBUS_FALSE and an infinite time_left)

Parameters

time_left storage for the remaining time.

Returns

GLOBUS_FALSE if time remaining
GLOBUS_TRUE if already timed out

globus_bool_t globus_callback_has_time_expired ( )

See if there is remaining time in a callback.

This function returns GLOBUS_TRUE if the running time of a callback has already expired. This function is intended to be called within a callback's stack, but is harmless to call anywhere (will return GLOBUS_FALSE)

Returns

GLOBUS_FALSE if time remaining
GLOBUS_TRUE if already timed out

void globus_callback_signal_poll ( )

Signal the poll.

This function signals globus_callback_space_poll() that something has changed and it should return to its caller as soon as possible.

In general, you never need to call this function directly. It is called (when necessary) by globus_cond_signal() or globus_cond_broadcast. The only case in which a user may wish to call this explicitly is if the application has no aspirations of ever being built threaded.

Returns

void

See Also: globus_callback_space_poll()

void globus_callback_space_poll	(	const globus_abstime_t *	timestop,
		globus_callback_space_t	space
	)

Poll for ready callbacks.

This function is used to poll for registered callbacks.

For non-threaded builds, callbacks are not/can not be delivered unless this is called. Any call to this can cause callbacks registered with the 'global' space to be fired. Whereas callbacks registered with a user's space will only be delivered when this is called with that space.

For threaded builds, this only needs to be called to poll user spaces with behavior == GLOBUS_CALLBACK_SPACE_BEHAVIOR_SINGLE. The 'global' space and other user spaces are constantly polled in a separate thread. (If it is called in a threaded build for these spaces, it will just yield its thread)

In general, you never need to call this function directly. It is called (when necessary) by globus_cond_wait(). The only case in which a user may wish to call this explicitly is if the application has no aspirations of ever being built threaded.

This function (when not yielding) will block up to timestop or until globus_callback_signal_poll() is called by one of the fired callbacks. It will always try and kick out ready callbacks, regardless of the timestop.

Parameters

timestop	The time to block until. If this is NULL or less than the cuurent time, an attempt to fire only ready callbacks is made (no blocking).
space	The callback space to poll. Note: regardless of what space is passed here, the 'global' space is also always polled.

See Also: Globus Callback Spaces; globus_condattr_setspace()

globus_result_t globus_callback_space_register_oneshot	(	globus_callback_handle_t *	callback_handle,
		const globus_reltime_t *	delay_time,
		globus_callback_func_t	callback_func,
		void *	callback_user_arg,
		globus_callback_space_t	space
	)

Register a oneshot some delay from now.

This function registers the callback_func to start some delay_time from now.

Parameters

callback_handle	Storage for a handle. This may be NULL. If it is NOT NULL, you must unregister the callback to reclaim resources.
delay_time	The relative time from now to fire this callback. If NULL, will fire as soon as possible
callback_func	the user func to call
callback_user_arg	user arg that will be passed to callback
space	The space with which to register this callback

Returns

GLOBUS_CALLBACK_ERROR_INVALID_ARGUMENT
GLOBUS_CALLBACK_ERROR_MEMORY_ALLOC
GLOBUS_SUCCESS

See Also: globus_callback_func_t; Globus Callback Spaces

globus_result_t globus_callback_space_register_periodic	(	globus_callback_handle_t *	callback_handle,
		const globus_reltime_t *	delay_time,
		const globus_reltime_t *	period,
		globus_callback_func_t	callback_func,
		void *	callback_user_arg,
		globus_callback_space_t	space
	)

Register a periodic callback.

This function registers a periodic callback_func to start some delay_time and run every period from then.

Parameters

callback_handle	Storage for a handle. This may be NULL. If it is NOT NULL, you must cancel the periodic to reclaim resources.
delay_time	The relative time from now to fire this callback. If NULL, will fire the first callback as soon as possible
period	The relative period of this callback
callback_func	the user func to call
callback_user_arg	user arg that will be passed to callback
space	The space with which to register this callback

Returns

GLOBUS_CALLBACK_ERROR_INVALID_ARGUMENT
GLOBUS_CALLBACK_ERROR_MEMORY_ALLOC
GLOBUS_SUCCESS

See Also: globus_callback_unregister(); globus_callback_func_t; globus_callback_spaces

globus_result_t globus_callback_unregister	(	globus_callback_handle_t	callback_handle,
		globus_callback_func_t	unregister_callback,
		void *	unreg_arg,
		globus_bool_t *	active
	)

Unregister a callback.

This function will cancel a callback and free the resources associated with the callback handle. If the callback was able to be canceled immediately (or if it has already run), GLOBUS_SUCCESS is returned and it is guaranteed that there are no running instances of the callback.

If the callback is currently running (or unstoppably about to be run), then the callback is prevented from being requeued, but, the 'official' cancel is deferred until the last running instance of the callback returns. If you need to know when the callback is guaranteed to have been canceled, pass an unregister callback.

If you would like to know if you unregistered a callback before it ran, pass storage for a boolean 'active'. This will be GLOBUS_TRUE if callback was running. GLOBUS_FALSE otherwise.

Parameters

callback_handle	the handle received from a globus_callback_space_register_*() call
unregister_callback	the function to call when the callback has been canceled and there are no running instances of it. This will be delivered to the same space used in the register call.
unreg_arg	user arg that will be passed to the unregister callback
active	storage for an indication of whether the callback was running when this call was made

Returns

GLOBUS_CALLBACK_ERROR_INVALID_CALLBACK_HANDLE
GLOBUS_CALLBACK_ERROR_ALREADY_CANCELED
GLOBUS_SUCCESS

See Also: globus_callback_space_register_periodic(); globus_callback_func_t

globus_bool_t globus_callback_was_restarted ( )

See if a callback has been restarted.

If the callback is a oneshot, this merely means the callback called globus_thread_blocking_space_will_block (or globus_cond_wait() at some point.

For a periodic, it signifies the same and also that the periodic has been requeued. This means that the callback function may be reentered if the period is short enough (on a threaded build)

Returns

GLOBUS_FALSE if not restarted
GLOBUS_TRUE if restarted

Convenience Macros

Callback Prototypes

Oneshot Callbacks

Periodic Callbacks

Callback Polling

Miscellaneous

Detailed Description

Macro Definition Documentation

Typedef Documentation

Function Documentation