globus_callback_spaces - Globus Callback Spaces

       Generated automatically by Doxygen for globus_common from the source code.

globus_common                                     Version 18.14                        globus_callback_spaces(3)

       Globus Callback Spaces.

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

       EnumeratorGLOBUS_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

voidglobus_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).

       Parameterswakeup 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_tglobus_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)

       Parameterstime_left storage for the remaining time.

       Returns

           • GLOBUS_FALSE if time remaining

           • GLOBUS_TRUE if already timed out

   globus_bool_tglobus_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_tglobus_callback_space_attr_destroy(globus_callback_space_attr_tattr)
       Destroy a space attr.

       Parametersattr attr to destroy, previously initialized with globus_callback_space_attr_init()Returns

           • GLOBUS_CALLBACK_ERROR_INVALID_ARGUMENT on NULL attr

           • GLOBUS_SUCCESS

       Seealsoglobus_callback_space_attr_init()globus_result_tglobus_callback_space_attr_get_behavior(globus_callback_space_attr_tattr,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.

       Parametersattr attr on which to query behavior
           behavior storage for the behavior

       Returns

           • GLOBUS_CALLBACK_ERROR_INVALID_ARGUMENT

           • GLOBUS_SUCCESS

   globus_result_tglobus_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

       Parametersattr 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_tglobus_callback_space_attr_set_behavior(globus_callback_space_attr_tattr,globus_callback_space_behavior_tbehavior)
       Set the behavior of a space.

       Parametersattr attr to associate behavior with
           behavior desired behavior

       Returns

           • GLOBUS_CALLBACK_ERROR_INVALID_ARGUMENT

           • GLOBUS_SUCCESS

       Seealsoglobus_callback_space_behavior_tglobus_result_tglobus_callback_space_destroy(globus_callback_space_tspace)
       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.

       Parametersspace  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

       Seealsoglobus_callback_space_init()globus_callback_space_reference()globus_result_tglobus_callback_space_get(globus_callback_space_t*space)
       Retrieve the space of a currently running callback.

       Parametersspace 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

   intglobus_callback_space_get_depth(globus_callback_space_tspace)
       Retrieve the current nesting level of a space.

       Parametersspace The space to query.

       Returns

           • the current nesting level

           • -1 on invalid space

   globus_result_tglobus_callback_space_init(globus_callback_space_t*space,globus_callback_space_attr_tattr)
       Initialize a user space. This creates a user space.

       Parametersspace    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

       Seealsoglobus_condattr_setspace()

           globus_io_attr_set_callback_space()

   globus_bool_tglobus_callback_space_is_single(globus_callback_space_tspace)
       See if the specified space is a single threaded behavior space.

       Parametersspace the space to query

       Returns

           • GLOBUS_TRUE if space's behavior is _BEHAVIOR_SINGLE

           • GLOBUS_FALSE otherwise

   globus_result_tglobus_callback_space_reference(globus_callback_space_tspace)
       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())

       Parametersspace space to reference

       Returns

           • GLOBUS_CALLBACK_ERROR_INVALID_SPACE

           • GLOBUS_SUCCESS

   globus_result_tglobus_callback_space_register_signal_handler(intsignum,globus_bool_tpersist,globus_callback_func_tcallback_func,void*callback_user_arg,globus_callback_space_tspace)
       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)

       Parameterssignum  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_tglobus_callback_unregister_signal_handler(intsignum,globus_callback_func_tunregister_callback,void*unreg_arg)
       Unregister a signal handling callback.

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

#defineGLOBUS_CALLBACK_GLOBAL_SPACE
       Global callback space. The 'global' space handle.

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

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

       globus_callback_spaces - Globus Callback Spaces

        - Globus Callback Spaces.

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_tglobus_callback_space_init (globus_callback_space_t *space, globus_callback_space_attr_t
           attr)
           Initialize a user space.
       globus_result_tglobus_callback_space_reference (globus_callback_space_t space)
           Take a reference to a space.
       globus_result_tglobus_callback_space_destroy (globus_callback_space_t space)
           Destroy a reference to a user space.
       globus_result_tglobus_callback_space_attr_init (globus_callback_space_attr_t *attr)
           Initialize a space attr.
       globus_result_tglobus_callback_space_attr_destroy (globus_callback_space_attr_t attr)
           Destroy a space attr.
       globus_result_tglobus_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_tglobus_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_tglobus_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_tglobus_callback_space_is_single (globus_callback_space_t space)
           See if the specified space is a single threaded behavior space.
       globus_bool_tglobus_callback_get_timeout (globus_reltime_t *time_left)
           Get the amount of time left in a callback.
       globus_bool_tglobus_callback_has_time_expired ()
           See if there is remaining time in a callback.
       globus_bool_tglobus_callback_was_restarted ()
           See if a callback has been restarted.
       globus_result_tglobus_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_tglobus_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