Man Linux: Main Page and Category List

NAME

       Globus Callback API -

   Callback Prototypes
       typedef void(* globus_callback_func_t )(void *user_arg)

   Oneshot Callbacks
       globus_result_t globus_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)

   Periodic Callbacks
       globus_result_t globus_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)
       globus_result_t globus_callback_unregister (globus_callback_handle_t
           callback_handle, globus_callback_func_t unregister_callback, void
           *unreg_arg, globus_bool_t *active)
       globus_result_t globus_callback_adjust_oneshot
           (globus_callback_handle_t callback_handle, const globus_reltime_t
           *new_delay)
       globus_result_t globus_callback_adjust_period (globus_callback_handle_t
           callback_handle, const globus_reltime_t *new_period)

   Callback Polling
       void globus_callback_space_poll (const globus_abstime_t *timestop,
           globus_callback_space_t space)
       void globus_callback_signal_poll ()

   Miscellaneous
       globus_bool_t globus_callback_get_timeout (globus_reltime_t *time_left)
       globus_bool_t globus_callback_has_time_expired ()
       globus_bool_t globus_callback_was_restarted ()

   Convenience Macros
       #define globus_callback_poll(a)
       #define globus_poll_blocking()
       #define globus_poll_nonblocking()
       #define globus_poll()
       #define globus_signal_poll()
       #define
           globus_callback_register_oneshot(callback_handle,delay_time,callback_func,callback_user_arg)
       #define
           globus_callback_register_periodic(callback_handle,delay_time,period,callback_func,callback_user_arg)
       #define
           globus_callback_register_signal_handler(signum,persist,callback_func,callback_user_arg)

Detailed Description

Define Documentation

   #define globus_callback_poll(a)
       Specifies the global space for globus_callback_space_poll(). argument
       is the timeout

       See also:
           globus_callback_space_poll()

   #define globus_poll_blocking()
       Specifies that globus_callback_space_poll() should poll on the global
       space with an infinite timeout. See also:
           globus_callback_space_poll()

   #define globus_poll_nonblocking()
       Specifies that globus_callback_space_poll() should poll on the global
       space with an immediate timeout. See also:
           globus_callback_space_poll()

   #define globus_poll()
       Specifies that globus_callback_space_poll() should poll on the global
       space with an immediate timeout. See also:
           globus_callback_space_poll()

   #define globus_signal_poll()
       Counterpart to globus_poll(). See also:
           globus_callback_signal_poll()

   #define globus_callback_register_oneshot(callback_handle, delay_time,
       callback_func, callback_user_arg)
       Specifies the global space for globus_callback_space_register_oneshot()
       all other arguments are the same as specified there. See also:
           globus_callback_space_register_oneshot()

   #define globus_callback_register_periodic(callback_handle, delay_time,
       period, callback_func, callback_user_arg)
       Specifies the global space for
       globus_callback_space_register_periodic() all other arguments are the
       same as specified there. See also:
           globus_callback_space_register_periodic()

   #define globus_callback_register_signal_handler(signum, persist,
       callback_func, callback_user_arg)
       Specifies the global space for
       globus_callback_space_register_signal_handler() all other arguments are
       the same as specified there. See also:
           globus_callback_space_register_signal_handler()

Typedef Documentation

   typedef void(* 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()

       Parameters:
           user_arg The user argument registered with this callback

       Returns:

           · void

       See also:
           globus_callback_space_register_oneshot()

           globus_callback_space_register_periodic()

           globus_thread_blocking_space_will_block()

           globus_callback_get_timeout()

Function Documentation

   globus_result_t globus_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. This function registers the
       callback_func to start some delay_time from now.

       Parameters:
           callback_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

       See also:
           globus_callback_func_t

           Globus Callback Spaces

   globus_result_t globus_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. This function registers a periodic
       callback_func to start some delay_time and run every period from then.

       Parameters:
           callback_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

       See also:
           globus_callback_unregister()

           globus_callback_func_t

           Globus Callback Spaces

   globus_result_t globus_callback_unregister (globus_callback_handle_t
       callback_handle, globus_callback_func_t unregister_callback, void *
       unreg_arg, globus_bool_t * active)
       Unregister a callback. This function will cancel a callback and free
       the resources associcated 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.

       Parameters:
           callback_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

       See also:
           globus_callback_space_register_periodic()

           globus_callback_func_t

   globus_result_t globus_callback_adjust_oneshot (globus_callback_handle_t
       callback_handle, const globus_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.

       Parameters:
           callback_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

       See also:
           globus_callback_space_register_periodic()

   globus_result_t globus_callback_adjust_period (globus_callback_handle_t
       callback_handle, const globus_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.

       Parameters:
           callback_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

       See also:
           globus_callback_space_register_periodic()

   void globus_callback_space_poll (const globus_abstime_t * timestop,
       globus_callback_space_t space)
       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.

       Parameters:
           timestop 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.

       Returns:

           · void

       See also:
           Globus Callback Spaces

           globus_condattr_setspace()

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

       See also:
           globus_callback_space_poll()

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