Globus Callback Spaces
Collaboration diagram for Globus Callback Spaces:

Defines

Enumerations

Functions


Detailed Description

View documentation without frames
View documentation with frames

Define Documentation

Global callback space.

The 'global' space handle.

This is the default space handle implied if no spaces are explicitly created.


Enumeration Type Documentation

Callback space behaviors describe how a space behaves.

In a non-threaded build all spaces exhibit a behavior == _BEHAVIOR_SINGLE. Setting a specific behavior in this case is ignored.

In a threaded build, _BEHAVIOR_SINGLE retains all the rules and behaviors of a non-threaded build while _BEHAVIOR_THREADED makes the space act as the global space.

Setting a space's behavior to _BEHAVIOR_SINGLE guarantees that the poll protection will always be there and all callbacks are serialized and only kicked out when polled for. In a threaded build, it is still necessary to poll for callbacks in a _BEHAVIOR_SINGLE space. (globus_cond_wait() will take care of this for you also)

Setting a space's behavior to _BEHAVIOR_SERIALIZED guarantees that the poll protection will always be there and all callbacks are serialized. In a threaded build, it is NOT necessary to poll for callbacks in a _BEHAVIOR_SERIALIZED space. Callbacks in this space will be delivered as soon as possible, but only one outstanding (and unblocked) callback will be allowed at any time.

Setting a space's behavior to _BEHAVIOR_THREADED allows the user to have the poll protection provided by spaces when built non-threaded, yet, be fully threaded when built threaded (where poll protection is not needed)

Enumerator:
GLOBUS_CALLBACK_SPACE_BEHAVIOR_SINGLE 

The default behavior.

Indicates that you always want poll protection and single threaded behavior (callbacks need to be explicitly polled for

GLOBUS_CALLBACK_SPACE_BEHAVIOR_SERIALIZED 

Indicates that you want poll protection and all callbacks to be serialized (but they do not need to be polled for in a threaded build)

GLOBUS_CALLBACK_SPACE_BEHAVIOR_THREADED 

Indicates that you only want poll protection.


Function Documentation

Initialize a user space.

This creates a user space.

Parameters:
spacestorage for the initialized space handle. This must be destroyed with globus_callback_space_destroy()
attra space attr descibing desired behaviors. If GLOBUS_NULL, the default behavior of GLOBUS_CALLBACK_SPACE_BEHAVIOR_SINGLE is assumed. This attr is copied into the space, so it is acceptable to destroy the attr as soon as it is no longer needed
Returns:
  • GLOBUS_CALLBACK_ERROR_INVALID_ARGUMENT on NULL space
  • GLOBUS_CALLBACK_ERROR_MEMORY_ALLOC
  • GLOBUS_SUCCESS
See also:
globus_condattr_setspace()
globus_io_attr_set_callback_space()

Take a reference to a space.

A library which has been 'given' a space to provide callbacks on would use this to take a reference on the user's space. This prevents mayhem should a user destroy a space before the library is done with it. This reference should be destroyed with globus_callback_space_destroy() (think dup())

Parameters:
spacespace to reference
Returns:
  • GLOBUS_CALLBACK_ERROR_INVALID_SPACE
  • GLOBUS_SUCCESS

Destroy a reference to a user space.

This will destroy a reference to a previously initialized space. Space will not actually be destroyed until all callbacks registered with this space have been run and unregistered (if the user has a handle to that callback) AND all references (from globus_callback_space_reference()) have been destroyed.

Parameters:
spacespace to destroy, previously initialized by globus_callback_space_init() or referenced with globus_callback_space_reference()
Returns:
  • GLOBUS_CALLBACK_ERROR_INVALID_SPACE
  • GLOBUS_SUCCESS
See also:
globus_callback_space_init()
globus_callback_space_reference()

Initialize a space attr.

Currently, the only attr to set is the behavior. The default behavior associated with this attr is GLOBUS_CALLBACK_SPACE_BEHAVIOR_SINGLE

Parameters:
attrstorage for the intialized attr. Must be destroyed with globus_callback_space_attr_destroy()
Returns:
  • GLOBUS_CALLBACK_ERROR_INVALID_ARGUMENT on NULL attr
  • GLOBUS_CALLBACK_ERROR_MEMORY_ALLOC
  • GLOBUS_SUCCESS

Destroy a space attr.

Parameters:
attrattr to destroy, previously initialized with globus_callback_space_attr_init()
Returns:
  • GLOBUS_CALLBACK_ERROR_INVALID_ARGUMENT on NULL attr
  • GLOBUS_SUCCESS
See also:
globus_callback_space_attr_init()

Set the behavior of a space.

Parameters:
attrattr to associate behavior with
behaviordesired behavior
Returns:
  • GLOBUS_CALLBACK_ERROR_INVALID_ARGUMENT
  • GLOBUS_SUCCESS
See also:
globus_callback_space_behavior_t

Get the behavior associated with an attr.

Note: for a non-threaded build, this will always pass back a behavior == GLOBUS_CALLBACK_SPACE_BEHAVIOR_SINGLE.

Parameters:
attrattr on which to query behavior
behaviorstorage for the behavior
Returns:
  • GLOBUS_CALLBACK_ERROR_INVALID_ARGUMENT
  • GLOBUS_SUCCESS
globus_result_t globus_callback_space_get ( globus_callback_space_t space)

Retrieve the space of a currently running callback.

Parameters:
spacestorage for the handle to the space currently running
Returns:
  • GLOBUS_CALLBACK_ERROR_INVALID_ARGUMENT on NULL space
  • GLOBUS_CALLBACK_ERROR_NO_ACTIVE_CALLBACK
  • GLOBUS_SUCCESS

Retrieve the current nesting level of a space.

Parameters:
spaceThe space to query.
Returns:
  • the current nesting level
  • -1 on invalid space

See if the specified space is a single threaded behavior space.

Parameters:
spacethe space to query
Returns:
  • GLOBUS_TRUE if space's behavior is _BEHAVIOR_SINGLE
  • GLOBUS_FALSE otherwise