globus_callback_api - Globus Callback API

       Generated automatically by Doxygen for globus_common from the source code.

globus_common                                     Version 18.14                           globus_callback_api(3)

       Globus Callback API.

globus_result_tglobus_callback_adjust_oneshot(globus_callback_handle_tcallback_handle,constglobus_reltime_t*new_delay)
       Adjust the delay of a oneshot callback. This function allows a user to adjust the delay of a previously
       registered callback. It is safe to call this within or outside of the callback that is being modified.

       Note if the oneshot has already been fired, this function will still return GLOBUS_SUCCESS, but won't
       affect anything.

       Parameterscallback_handle the handle received from a globus_callback_space_register_oneshot() call
           new_delay The new delay from now. If NULL, then callback will be fired as soon as possible.

       Returns

           • GLOBUS_CALLBACK_ERROR_INVALID_CALLBACK_HANDLE

           • GLOBUS_CALLBACK_ERROR_ALREADY_CANCELED

           • GLOBUS_SUCCESS

       Seealsoglobus_callback_space_register_periodic()globus_result_tglobus_callback_adjust_period(globus_callback_handle_tcallback_handle,constglobus_reltime_t*new_period)
       Adjust the period of a periodic callback. This  function  allows  a  user  to  adjust  the  period  of  a
       previously  registered  callback. It is safe to call this within or outside of the callback that is being
       modified.

       This func also allows a user to effectively 'suspend' a periodic callback until another time by passing a
       period of NULL. The callback can later be resumed by passing in a new period.

       Note that the callback will not be fired sooner than 'new_period' from now. A 'suspended'  callback  must
       still be unregistered to free its resources.

       Parameterscallback_handle the handle received from a globus_callback_space_register_periodic() call
           new_period The new period. If NULL or globus_i_reltime_infinity, then callback will be 'suspended' as
           soon as the last running instance of it returns.

       Returns

           • GLOBUS_CALLBACK_ERROR_INVALID_CALLBACK_HANDLE

           • GLOBUS_CALLBACK_ERROR_ALREADY_CANCELED

           • GLOBUS_SUCCESS

       Seealsoglobus_callback_space_register_periodic()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

   voidglobus_callback_signal_poll()
       Signal the poll. This function signals globus_callback_space_poll() that something  has  changed  and  it
       should return to its caller as soon as possible.

       In  general,  you  never  need  to  call  this  function  directly.  It  is  called  (when  necessary) by
       globus_cond_signal() or globus_cond_broadcast. The only case in which  a  user  may  wish  to  call  this
       explicitly is if the application has no aspirations of ever being built threaded.

       Returns

           • void

       Seealsoglobus_callback_space_poll()voidglobus_callback_space_poll(constglobus_abstime_t*timestop,globus_callback_space_tspace)
       Poll for ready callbacks. This function is used to poll for registered callbacks.

       For  non-threaded  builds, callbacks are not/can not be delivered unless this is called. Any call to this
       can cause callbacks registered with the 'global' space to be fired. Whereas callbacks registered  with  a
       user's space will only be delivered when this is called with that space.

       For   threaded   builds,   this   only  needs  to  be  called  to  poll  user  spaces  with  behavior  ==
       GLOBUS_CALLBACK_SPACE_BEHAVIOR_SINGLE. The 'global' space and other user spaces are constantly polled  in
       a separate thread.
        (If it is called in a threaded build for these spaces, it will just yield its thread)

       In  general,  you  never  need  to  call  this  function  directly.  It  is  called  (when  necessary) by
       globus_cond_wait(). The only case in which a user may wish to call this explicitly is if the  application
       has no aspirations of ever being built threaded.

       This  function  (when  not  yielding) will block up to timestop or until globus_callback_signal_poll() is
       called by one of the fired callbacks. It will always try and kick out ready callbacks, regardless of  the
       timestop.

       Parameterstimestop  The  time to block until. If this is NULL or less than the cuurent time, an attempt to fire
           only ready callbacks is made (no blocking).
           space The callback space to poll. Note: regardless of what space is passed here, the  'global'  space
           is also always polled.

       SeealsoGlobusCallbackSpacesglobus_condattr_setspace()globus_result_tglobus_callback_space_register_oneshot(globus_callback_handle_t*callback_handle,constglobus_reltime_t*delay_time,globus_callback_func_tcallback_func,void*callback_user_arg,globus_callback_space_tspace)
       Register  a  oneshot  some  delay  from  now.  This  function  registers  the callback_func to start some
       delay_time from now.

       Parameterscallback_handle Storage for a handle. This may be NULL. If it is NOT NULL, you  must  unregister  the
           callback to reclaim resources.
           delay_time The relative time from now to fire this callback. If NULL, will fire as soon as possible
           callback_func the user func to call
           callback_user_arg user arg that will be passed to callback
           space The space with which to register this callback

       Returns

           • GLOBUS_CALLBACK_ERROR_INVALID_ARGUMENT

           • GLOBUS_CALLBACK_ERROR_MEMORY_ALLOC

           • GLOBUS_SUCCESS

       Seealsoglobus_callback_func_tGlobusCallbackSpacesglobus_result_tglobus_callback_space_register_periodic(globus_callback_handle_t*callback_handle,constglobus_reltime_t*delay_time,constglobus_reltime_t*period,globus_callback_func_tcallback_func,void*callback_user_arg,globus_callback_space_tspace)
       Register  a  periodic callback. This function registers a periodic callback_func to start some delay_time
       and run every period from then.

       Parameterscallback_handle Storage for a handle. This may be NULL. If it  is  NOT  NULL,  you  must  cancel  the
           periodic to reclaim resources.
           delay_time The relative time from now to fire this callback. If NULL, will fire the first callback as
           soon as possible
           period The relative period of this callback
           callback_func the user func to call
           callback_user_arg user arg that will be passed to callback
           space The space with which to register this callback

       Returns

           • GLOBUS_CALLBACK_ERROR_INVALID_ARGUMENT

           • GLOBUS_CALLBACK_ERROR_MEMORY_ALLOC

           • GLOBUS_SUCCESS

       Seealsoglobus_callback_unregister()globus_callback_func_tglobus_callback_spacesglobus_result_tglobus_callback_unregister(globus_callback_handle_tcallback_handle,globus_callback_func_tunregister_callback,void*unreg_arg,globus_bool_t*active)
       Unregister a callback. This function will cancel a callback and free the resources  associated  with  the
       callback  handle.  If  the  callback  was  able  to  be  canceled immediately (or if it has already run),
       GLOBUS_SUCCESS is returned and it is guaranteed that there are no running instances of the callback.

       If the callback is currently running (or unstoppably about to be run), then  the  callback  is  prevented
       from  being  requeued,  but,  the  'official'  cancel  is deferred until the last running instance of the
       callback returns. If you need to know when the callback is guaranteed to  have  been  canceled,  pass  an
       unregister callback.

       If  you  would  like  to  know  if  you unregistered a callback before it ran, pass storage for a boolean
       'active'. This will be GLOBUS_TRUE if callback was running. GLOBUS_FALSE otherwise.

       Parameterscallback_handle the handle received from a globus_callback_space_register_*() call
           unregister_callback the function to call when the callback has been canceled and there are no running
           instances of it. This will be delivered to the same space used in the register call.
           unreg_arg user arg that will be passed to the unregister callback
           active storage for an indication of whether the callback was running when this call was made

       Returns

           • GLOBUS_CALLBACK_ERROR_INVALID_CALLBACK_HANDLE

           • GLOBUS_CALLBACK_ERROR_ALREADY_CANCELED

           • GLOBUS_SUCCESS

       Seealsoglobus_callback_space_register_periodic()globus_callback_func_tglobus_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_poll(a)
       Poll the global callback space. Specifies the global space for globus_callback_space_poll(). argument is
       the timeout

       Seealsoglobus_callback_space_poll()#defineglobus_callback_register_oneshot(callback_handle,delay_time,callback_func,callback_user_arg)
       Register a oneshot function in the global callback space. Specifies the global space for
       globus_callback_space_register_oneshot() all other arguments are the same as specified there.

       Seealsoglobus_callback_space_register_oneshot()#defineglobus_callback_register_periodic(callback_handle,delay_time,period,callback_func,callback_user_arg)
       Register a periodic function in the global callback space. Specifies the global space for
       globus_callback_space_register_periodic() all other arguments are the same as specified there.

       Seealsoglobus_callback_space_register_periodic()#defineglobus_callback_register_signal_handler(signum,persist,callback_func,callback_user_arg)
       Register a signal handler in the global callback space. Specifies the global space for
       globus_callback_space_register_signal_handler() all other arguments are the same as specified there.

       Seealsoglobus_callback_space_register_signal_handler()#defineglobus_poll()
       Nonblocking poll of the global callback space. Specifies that globus_callback_space_poll() should poll on
       the global space with an immediate timeout

       Seealsoglobus_callback_space_poll()#defineglobus_poll_blocking()
       Blocking poll of the global callback space. Specifies that globus_callback_space_poll() should poll on
       the global space with an infinite timeout

       Seealsoglobus_callback_space_poll()#defineglobus_poll_nonblocking()
       Nonblocking poll of the global callback space. Specifies that globus_callback_space_poll() should poll on
       the global space with an immediate timeout

       Seealsoglobus_callback_space_poll()#defineglobus_signal_poll()
       Wake up callback polling thread. Counterpart to globus_poll().

       Seealsoglobus_callback_signal_poll()

       globus_callback_api - Globus Callback API

        - Globus Callback API.

CallbackPrototypes
       typedef void(* globus_callback_func_t) (void *user_arg)
           Globus callback prototype.

   OneshotCallbacksglobus_result_tglobus_callback_space_register_oneshot (globus_callback_handle_t *callback_handle, const
           globus_reltime_t *delay_time, globus_callback_func_t callback_func, void *callback_user_arg,
           globus_callback_space_t space)
           Register a oneshot some delay from now.

   PeriodicCallbacksglobus_result_tglobus_callback_space_register_periodic (globus_callback_handle_t *callback_handle, const
           globus_reltime_t *delay_time, const globus_reltime_t *period, globus_callback_func_t callback_func,
           void *callback_user_arg, globus_callback_space_t space)
           Register a periodic callback.
       globus_result_tglobus_callback_unregister (globus_callback_handle_t callback_handle,
           globus_callback_func_t unregister_callback, void *unreg_arg, globus_bool_t *active)
           Unregister a callback.
       globus_result_tglobus_callback_adjust_oneshot (globus_callback_handle_t callback_handle, const
           globus_reltime_t *new_delay)
           Adjust the delay of a oneshot callback.
       globus_result_tglobus_callback_adjust_period (globus_callback_handle_t callback_handle, const
           globus_reltime_t *new_period)
           Adjust the period of a periodic callback.

   CallbackPolling
       void globus_callback_space_poll (const globus_abstime_t *timestop, globus_callback_space_t space)
           Poll for ready callbacks.
       void globus_callback_signal_poll ()
           Signal the poll.

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

   ConvenienceMacros
       #define globus_callback_poll(a)
           Poll the global callback space.
       #define globus_poll_blocking()
           Blocking poll of the global callback space.
       #define globus_poll_nonblocking()
           Nonblocking poll of the global callback space.
       #define globus_poll()
           Nonblocking poll of the global callback space.
       #define globus_signal_poll()
           Wake up callback polling thread.
       #define globus_callback_register_oneshot( callback_handle,  delay_time,  callback_func,
           callback_user_arg)
           Register a oneshot function in the global callback space.
       #define globus_callback_register_periodic( callback_handle,  delay_time,  period,  callback_func,
           callback_user_arg)
           Register a periodic function in the global callback space.
       #define globus_callback_register_signal_handler( signum,  persist,  callback_func,  callback_user_arg)
           Register a signal handler in the global callback space.

typedefvoid(*globus_callback_func_t)(void*user_arg)
       Globus callback prototype. This is the signature of the function registered with the
       globus_callback_register_* calls.

       If this is a periodic callback, it is guaranteed that the call canNOT be reentered unless
       globus_thread_blocking_space_will_block() is called (explicitly, or implicitly via globus_cond_wait()).
       Also, if globus_callback_unregister() is called to cancel this periodic from within this callback, it is
       guaranteed that the callback will NOT be requeued again

       If the function will block at all, the user should call globus_callback_get_timeout() to see how long
       this function can safely block or call globus_thread_blocking_space_will_block()

       Parametersuser_arg The user argument registered with this callback

       Seealsoglobus_callback_space_register_oneshot()globus_callback_space_register_periodic()

           globus_thread_blocking_space_will_block()

           globus_callback_get_timeout()