Grid Community Toolkit  6.2.1705709074 (tag: v6.2.20240202)
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Macros | Enumerations | Functions
Globus Callback Spaces

Globus Callback Spaces. More...

Macros

#define GLOBUS_CALLBACK_GLOBAL_SPACE
 Global callback space. More...
 

Enumerations

enum  globus_callback_space_behavior_t { GLOBUS_CALLBACK_SPACE_BEHAVIOR_SINGLE, GLOBUS_CALLBACK_SPACE_BEHAVIOR_SERIALIZED, GLOBUS_CALLBACK_SPACE_BEHAVIOR_THREADED }
 Callback space behaviors describe how a space behaves. More...
 

Functions

globus_result_t globus_callback_space_init (globus_callback_space_t *space, globus_callback_space_attr_t attr)
 Initialize a user space. More...
 
globus_result_t globus_callback_space_reference (globus_callback_space_t space)
 Take a reference to a space. More...
 
globus_result_t globus_callback_space_destroy (globus_callback_space_t space)
 Destroy a reference to a user space. More...
 
globus_result_t globus_callback_space_attr_init (globus_callback_space_attr_t *attr)
 Initialize a space attr. More...
 
globus_result_t globus_callback_space_attr_destroy (globus_callback_space_attr_t attr)
 Destroy a space attr. More...
 
globus_result_t globus_callback_space_attr_set_behavior (globus_callback_space_attr_t attr, globus_callback_space_behavior_t behavior)
 Set the behavior of a space. More...
 
globus_result_t globus_callback_space_attr_get_behavior (globus_callback_space_attr_t attr, globus_callback_space_behavior_t *behavior)
 Get the behavior associated with an attr. More...
 
globus_result_t globus_callback_space_get (globus_callback_space_t *space)
 Retrieve the space of a currently running callback. More...
 
int globus_callback_space_get_depth (globus_callback_space_t space)
 Retrieve the current nesting level of a space. More...
 
globus_bool_t globus_callback_space_is_single (globus_callback_space_t space)
 See if the specified space is a single threaded behavior space. More...
 

Detailed Description

Globus Callback Spaces.

Macro Definition Documentation

#define GLOBUS_CALLBACK_GLOBAL_SPACE

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

globus_result_t globus_callback_space_attr_destroy ( globus_callback_space_attr_t  attr)

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()
globus_result_t globus_callback_space_attr_get_behavior ( globus_callback_space_attr_t  attr,
globus_callback_space_behavior_t behavior 
)

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_attr_init ( globus_callback_space_attr_t attr)

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 initialized 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
globus_result_t globus_callback_space_attr_set_behavior ( globus_callback_space_attr_t  attr,
globus_callback_space_behavior_t  behavior 
)

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
globus_result_t globus_callback_space_destroy ( globus_callback_space_t  space)

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()
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
int globus_callback_space_get_depth ( globus_callback_space_t  space)

Retrieve the current nesting level of a space.

Parameters
spaceThe space to query.
Returns
  • the current nesting level
  • -1 on invalid space
globus_result_t globus_callback_space_init ( globus_callback_space_t space,
globus_callback_space_attr_t  attr 
)

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 describing 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()
globus_bool_t globus_callback_space_is_single ( globus_callback_space_t  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
globus_result_t globus_callback_space_reference ( globus_callback_space_t  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