--- name: "globus_callback_api" section: "3" platform: "linux" package: "libglobus-common-doc" version: "18.14-3" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/globus_callback_api" --- # globus\_callback\_api(3) Globus Callback API - Globus Callback API. ## NAME globus\_callback\_api - Globus Callback API \- Globus Callback API. ## SYNOPSIS ### Callback Prototypes typedef void(\* **globus\_callback\_func\_t**) (void \*user\_arg)\ Globus callback prototype. ### 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)\ Register a oneshot some delay from now. ### 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)\ Register a periodic callback. **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. **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. **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. ### Callback Polling 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. ### Miscellaneous **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. ### Convenience Macros \#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. ## Detailed Description Globus Callback API. ## Macro Definition Documentation ### #define globus\_callback\_poll(a) Poll the global callback space. Specifies the global space for **globus\_callback\_space\_poll()**. argument is the timeout **See also** **globus\_callback\_space\_poll()** ### #define globus\_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. **See also** **globus\_callback\_space\_register\_oneshot()** ### #define globus\_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. **See also** **globus\_callback\_space\_register\_periodic()** ### #define globus\_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. **See also** **globus\_callback\_space\_register\_signal\_handler()** ### #define globus\_poll() Nonblocking poll of the global callback space. 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\_blocking() Blocking poll of the global callback space. 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() Nonblocking poll of the global callback space. 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() Wake up callback polling thread. Counterpart to **globus\_poll()**. **See also** **globus\_callback\_signal\_poll()** ## 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 **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\_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()** ### 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 ### 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()** ### 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. **See also** **Globus Callback Spaces** **globus\_condattr\_setspace()** ### 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 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. **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\_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.