Provided by: libglobus-common-doc_18.14-1.1build1_all bug

NAME

       globus_callback_spaces - Globus Callback Spaces

        - Globus Callback Spaces.

SYNOPSIS

   Miscellaneous
       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.
       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.
       globus_bool_t globus_callback_get_timeout (globus_reltime_t *time_left)
           Get the amount of time left in a callback.
       globus_bool_t globus_callback_has_time_expired ()
           See if there is remaining time in a callback.
       globus_bool_t globus_callback_was_restarted ()
           See if a callback has been restarted.
       globus_result_t globus_callback_space_register_signal_handler (int signum, globus_bool_t
           persist, globus_callback_func_t callback_func, void *callback_user_arg,
           globus_callback_space_t space)
           Fire a callback when the specified signal is received.
       globus_result_t globus_callback_unregister_signal_handler (int signum,
           globus_callback_func_t unregister_callback, void *unreg_arg)
           Unregister a signal handling callback.
       void globus_callback_add_wakeup_handler (void(*wakeup)(void *), void *user_arg)
           Register a wakeup handler with callback library.
       #define GLOBUS_CALLBACK_GLOBAL_SPACE
           Global callback space.
       #define GLOBUS_SIGNAL_INTERRUPT

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.

   #define GLOBUS_SIGNAL_INTERRUPT
       Use this to trap interrupts (SIGINT on unix). In the future, this will also map to handle
       ctrl-C on win32.

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

   void globus_callback_add_wakeup_handler (void(*)(void *) wakeup, void * user_arg)
       Register a wakeup handler with callback library. This is really only needed in non-
       threaded builds, but for cross builds should be used everywhere that a callback may sleep
       for an extended period of time.

       An example use is for an io poller that sleeps indefinitely on select(). If the callback
       library receives a signal that it needs to deliver asap, it will call the wakeup
       handler(s), These wakeup handlers must run as though they were called from a signal
       handler (don't use any thread utilities). The io poll example will likely write a single
       byte to a pipe that select() is monitoring.

       This handler will not be unregistered until the callback library is deactivated (via
       common).

       Parameters
           wakeup function to call when callback library needs you to return asap from any
           blocked callbacks.
           user_arg user data that will be passed along in the wakeup handler

   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

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

   globus_result_t globus_callback_space_register_signal_handler (int signum, globus_bool_t
       persist, globus_callback_func_t callback_func, void * callback_user_arg,
       globus_callback_space_t space)
       Fire a callback when the specified signal is received. Note that there is a tiny delay
       between the time this call returns and the signal is actually handled by this library. It
       is likely that, if the signal was received the instant the call returned, it will be lost
       (this is normally not an issue, since you would call this in your startup code anyway)

       Parameters
           signum The signal to receive. The following signals are not allowed: SIGKILL, SIGSEGV,
           SIGABRT, SIGBUS, SIGFPE, SIGILL, SIGIOT, SIGPIPE, SIGEMT, SIGSYS, SIGTRAP, SIGSTOP,
           SIGCONT, and SIGWAITING
           persist If GLOBUS_TRUE, keep this callback registered for multiple signals. If
           GLOBUS_FALSE, the signal handler will automatically be unregistered once the signal
           has been received.
           callback_func the user func to call when a signal is received
           callback_user_arg user arg that will be passed to callback
           space the space to deliver callbacks to.

       Returns

           • GLOBUS_CALLBACK_ERROR_INVALID_SPACE

           • GLOBUS_CALLBACK_ERROR_INVALID_ARGUMENT

           • GLOBUS_SUCCESS otherwise

   globus_result_t globus_callback_unregister_signal_handler (int signum, globus_callback_func_t
       unregister_callback, void * unreg_arg)
       Unregister a signal handling callback.

       Parameters
           signum The signal to unregister.
           unregister_callback the function to call when the callback has been canceled and there
           are no running instances of it (may be NULL). This will be delivered to the same space
           used in the register call.
           unreg_arg user arg that will be passed to callback

       Returns

           • GLOBUS_CALLBACK_ERROR_INVALID_ARGUMENT if this signal was registered with persist ==
             false, then there is a race between a signal actually being caught and therefore
             automatically unregistered and the attempt to manually unregister it. If that race
             occurs, you will receive this error just as you would for any signal not registered.

           • GLOBUS_SUCCESS otherwise

   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

Author

       Generated automatically by Doxygen for globus_common from the source code.