NAME

       globus_callback_spaces

SYNOPSIS

   Macros
       #define GLOBUS_CALLBACK_GLOBAL_SPACE
           Global callback space.

   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. "

   Functions
       globus_result_t globus_callback_space_init (globus_callback_space_t *space,
           globus_callback_space_attr_t attr)
           Initialize a user space.
       globus_result_t globus_callback_space_reference (globus_callback_space_t space)
           Take a reference to a space.
       globus_result_t globus_callback_space_destroy (globus_callback_space_t space)
           Destroy a reference to a user space.
       globus_result_t globus_callback_space_attr_init (globus_callback_space_attr_t *attr)
           Initialize a space attr.
       globus_result_t globus_callback_space_attr_destroy (globus_callback_space_attr_t attr)
           Destroy a space attr.
       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.
       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.
       globus_result_t globus_callback_space_get (globus_callback_space_t *space)
           Retrieve the space of a currently running callback.
       int globus_callback_space_get_depth (globus_callback_space_t space)
           Retrieve the current nesting level of a 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.

Detailed Description

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

   enum globus_callback_space_behavior_t
       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:
           attr attr 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:
           attr attr on which to query behavior
           behavior storage 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:
           attr storage 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

   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:
           attr attr to associate behavior with
           behavior desired 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:
           space space 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:
           space storage 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:
           space The 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:
           space storage for the initialized space handle. This must be destroyed with
           globus_callback_space_destroy()
           attr a 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()

   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:
           space the 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:
           space space to reference

       Returns:

           • GLOBUS_CALLBACK_ERROR_INVALID_SPACE

           • GLOBUS_SUCCESS

Author

       Generated automatically by Doxygen for globus_common from the source code.