globus_callback_api(3)

📦
version 18.15 · 7 versions
, in epel 10, fedora 43, fedora 44, ubuntu resolute

✨ globus_callback_api(3) — Library Functions Manual ✨

okay bestie, welcome to the Globus Callback API 💖 this is the manual for globus_callback_api(3), and it's literally giving main character energy for all your callback needs. no cap, it's a whole vibe. 🦋

🌸 NAME 🌸

globus_callback_api — Globus Callback API.

  • Globus Callback API.

periodt. 💅

🦋 SYNOPSIS 🦋

okay so here's the whole vibe check of what's in this API. signatures stay exactly as they are, bestie — don't touch a single character. 🎀

💖 Callback Prototypes 💖

typedef void(* globus_callback_func_t) (void *user_arg)

Globus callback prototype. this is the blueprint for your callback function, iykyk ✨

✨ 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. one shot, one chance, no redo bestie ⭐

🎀 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)
  • globus_callback_space_register_periodic — Register a periodic callback. it keeps coming back like a situationship 😭
  • globus_callback_unregister — Unregister a callback. cancel that subscription, bestie
  • globus_callback_adjust_oneshot — Adjust the delay of a oneshot callback. change the timing, no drama
  • globus_callback_adjust_period — Adjust the period of a periodic callback. remix the rhythm ✨

🌈 Callback Polling 🌈

void globus_callback_space_poll (const globus_abstime_t *timestop,
    globus_callback_space_t space)
void globus_callback_signal_poll ()
  • globus_callback_space_poll — Poll for ready callbacks. vibe check on your callbacks
  • globus_callback_signal_poll — Signal the poll. poke it awake 💅

💜 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 ()
  • globus_callback_get_timeout — Get the amount of time left in a callback. clock check ⏰
  • globus_callback_has_time_expired — See if there is remaining time in a callback. is the time gone or not? 👀
  • globus_callback_was_restarted — See if a callback has been restarted. did it respawn? 🔥

🍓 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)
  • globus_callback_poll(a) — Poll the global callback space. global space, global vibes
  • globus_poll_blocking() — Blocking poll of the global callback space. it waits, no cap
  • globus_poll_nonblocking() — Nonblocking poll of the global callback space. zero patience energy
  • globus_poll() — Nonblocking poll of the global callback space. same as above but shorter ✨
  • globus_signal_poll() — Wake up callback polling thread. rise and grind ☀️
  • globus_callback_register_oneshot( callback_handle, delay_time, callback_func, callback_user_arg) — Register a oneshot function in the global callback space. one and done
  • globus_callback_register_periodic( callback_handle, delay_time, period, callback_func, callback_user_arg) — Register a periodic function in the global callback space. round and round 🔄
  • globus_callback_register_signal_handler( signum, persist, callback_func, callback_user_arg) — Register a signal handler in the global callback space. catch those signals 📡

🫶 Detailed Description 🫶

Globus Callback API. that's the whole mood, bestie 💖

👑 Macro Definition Documentation 👑

okay so these are the macro receipts, no skipping. every detail is here, fr fr. 🧚

#define globus_callback_poll( a)

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

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

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

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

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

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

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

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

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

to be continued in part 2... 💖

✨ Function Documentation ✨

🌸 globus_result_t globus_callback_adjust_oneshot (globus_callback_handle_t callback_handle, const globus_reltime_t * new_delay)

Okay so you registered a oneshot callback and now you're like "hmm bestie, actually, can we do that later?" — say less, this is the function. It lets you tweak the delay on a callback you already registered, and it's totally safe to call this from inside the callback you're modifying OR from outside it. Both vibes are valid. 💅

Heads up: if the oneshot has already fired, this still returns GLOBUS_SUCCESS, but it won't actually do anything. So like… success with zero consequences. Iconic but useless. 🙈

Parameters

  • callback_handle — the handle you got back from a globus_callback_space_register_oneshot() call
  • new_delay — the new delay counted from now. If it's NULL, the callback gets 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)

Same energy, but for the periodics. This one lets you change the period of a callback you already registered, and again — safe to call it inside the callback or outside it, no cap.

It also does a lil party trick: passing a period of NULL effectively 'suspends' a periodic callback until another time, and then you can bring it back by handing it a new period. Pause and unpause, main character behavior. ⏸️▶️

Careful bestie: the callback will not fire sooner than new_period from now. And a 'suspended' callback still has to be unregistered to free its resources — suspension is not a cleanup, it's a nap. 😴

Parameters

  • callback_handle — the handle you got back from a globus_callback_space_register_periodic() call
  • new_period — the new period. If it's NULL or globus_i_reltime_infinity, the callback gets '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)

Clock check! ⏰ This one grabs the remaining time a callback is allowed to run. If the callback has already timed out, time_left gets set to zero and you get GLOBUS_TRUE back.

It's intended to be called from within a callback's stack, but honestly it's harmless anywhere — if you call it elsewhere you'll just get GLOBUS_FALSE and an infinite time_left. Chill lil function. 🌈

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

The vibes-only version of the one above. It just tells you if the running time of a callback has already expired — GLOBUS_TRUE if it has.

Same deal: meant to be called within a callback's stack, but harmless anywhere else, where it'll just return GLOBUS_FALSE. 🫶

Returns

  • GLOBUS_FALSE if time remaining
  • GLOBUS_TRUE if already timed out

🌟 void globus_callback_signal_poll ()

This one just yells "HEY SOMETHING CHANGED!!" 📣 It signals globus_callback_space_poll() that things are different and it should head back to its caller ASAP.

Lowkey you never need to call this yourself. It gets called (when it needs to be) by globus_cond_signal() or globus_cond_broadcast. The one single case where you might call it explicitly is if your application has no aspirations of ever being built threaded. That's it. That's the whole exception. 💀

Returns

  • void

See also

  • globus_callback_space_poll()

🧚 void globus_callback_space_poll (const globus_abstime_t * timestop, globus_callback_space_t space)

Polling time bestie ✨ This is the function that polls for registered callbacks.

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

For threaded builds: you only need to call this to poll user spaces that have behavior == GLOBUS_CALLBACK_SPACE_BEHAVIOR_SINGLE. The 'global' space and the other user spaces are constantly polled in a separate thread. (And if you do call it in a threaded build for those spaces, it'll just yield its thread. Respectfully steps aside. 🙇)

Again, generally you never need to call this directly — it's called (when necessary) by globus_cond_wait(). The only case a user might want to call it explicitly is if the application has no aspirations of ever being built threaded.

When it's not yielding, this function will block up to timestop or until globus_callback_signal_poll() gets called by one of the fired callbacks. And it will always try and kick out ready callbacks, regardless of the timestop. Slay.

Parameters

  • timestop — the time to block until. If this is NULL or less than the current time, an attempt is made to fire only ready callbacks (no blocking at all).
  • space — the callback space to poll. Note: no matter what space you pass in 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)

The classic. Register a oneshot some delay from now — it sets up callback_func to start delay_time from now. One and done. 🎯

Parameters

  • callback_handle — storage for a handle. This may be NULL. But if it is NOT NULL, you must unregister the callback to reclaim resources. Don't leave it hanging bestie, that's a leak. 😭
  • delay_time — the relative time from now to fire this callback. If NULL, it'll fire as soon as possible
  • callback_func — the user func to call
  • callback_user_arg — user arg that will be passed to the 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)

It's giving… loop. 🔄 This registers a periodic callback_func to start some delay_time from now and then run every period after that. The gift that keeps on giving.

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, the first callback fires 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 the 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)

Okay this is the breakup function. 💔 It cancels a callback and frees the resources tied to the callback handle.

If the callback was able to be canceled immediately (or if it already ran), you get GLOBUS_SUCCESS back, and it is guaranteed that there are no running instances of the callback. Clean exit, no loose ends.

But if the callback is currently running (or unstoppably about to be run), then it gets prevented from being requeued, and the 'official' cancel is deferred until the last running instance of the callback returns. So if you need to know when the callback is guaranteed to be canceled, pass an unregister callback.

And if you wanna know whether you unregistered it before it ran, pass storage for a boolean active. That'll be GLOBUS_TRUE if the callback was running, and GLOBUS_FALSE otherwise.

Parameters

  • callback_handle — the handle you got 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 ()

Did it come back? 👀 This checks 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 thing and also that the periodic has been requeued. Which means the callback function may be reentered if the period is short enough (on a threaded build). So like, watch out, it can come back around. 😳

Returns

  • GLOBUS_FALSE if not restarted
  • GLOBUS_TRUE if restarted

👑 Author

Generated automatically by Doxygen for globus_common from the source code. No human wrote this by hand, it just appeared, fully formed, like a butterfly. 🦋

And that's a wrap on part 2 bestie!! 💖✨ This whole page is from globus_common, Version 18.15, and it's the globus_callback_api(3) manual page. Go forth and poll responsibly, register your callbacks, and always, ALWAYS unregister them. Periodt. 💅🎀🌸

📦 where this page comes from