globus_callback_spaces(3)

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

✨ globus_callback_spaces ✨

okay bestie, welcome to globus_callback_spaces(3) — the Globus Callback Spaces page, and honestly? it's giving infrastructure. it's the plumbing that decides when and how your callbacks get to run. let's get into it 💅

🦋 NAME 🦋

globus_callback_spaces — Globus Callback Spaces.

lowkey the name says it all. it's callback spaces. it's spaces for your callbacks. it's a whole vibe. 🫶

🌸 SYNOPSIS 🌸

Miscellaneous

here's the whole cast, no cap:

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_t globus_callback_space_init (globus_callback_space_t
    *space, globus_callback_space_attr_t attr)

Initialize a user space.

globus_result_t globus_callback_space_reference (globus_callback_space_t
    space)

Take a reference to a space.

globus_result_t globus_callback_space_destroy (globus_callback_space_t
    space)

Destroy a reference to a user space.

globus_result_t globus_callback_space_attr_init
    (globus_callback_space_attr_t *attr)

Initialize a space attr.

globus_result_t globus_callback_space_attr_destroy
    (globus_callback_space_attr_t attr)

Destroy a space attr.

globus_result_t globus_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_t globus_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_t globus_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_t globus_callback_space_is_single (globus_callback_space_t
    space)

See if the specified space is a single threaded behavior space.

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.

globus_result_t globus_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_t globus_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

Detailed Description

Globus Callback Spaces.

that's it. that's the detailed description. iconic minimalism honestly 💀

🎀 Macro Definition Documentation 🎀

#define GLOBUS_CALLBACK_GLOBAL_SPACE

Global callback space. The 'global' space handle.

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

so if you're out here just not making spaces? this one's your ride-or-die. the default. the main character. 👑

#define GLOBUS_SIGNAL_INTERRUPT

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

yes bestie, ctrl-C on win32 is on the roadmap. we're manifesting it. ✨

💖 Enumeration Type Documentation 💖

enum globus_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.

fr fr — if you're not threaded, every space is single and setting anything else just gets politely 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)

so _BEHAVIOR_SINGLE: poll protection always there, callbacks serialized, and they only get released when you poll for them. threaded build? you STILL gotta poll. globus_cond_wait() has your back though 🫶

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.

_BEHAVIOR_SERIALIZED: poll protection ✅, serialized callbacks ✅, and in a threaded build you do not have to poll. callbacks show up ASAP but — one at a time, bestie. only one outstanding (and unblocked) callback allowed at any given moment. 💅

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)

_BEHAVIOR_THREADED is the best-of-both-worlds one: poll protection when you're built non-threaded, fully threaded when you're built threaded (where you don't need poll protection anyway). slay. 🌈

Enumerator

  • GLOBUS_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

okay that's part 1 bestie, hold on, there's more coming 💜

💖 FUNCTION DOCUMENTATION 💖

okay bestie, deep breath, this is the part where we actually meet the functions one by one. every single one. no skipping. grab a snack 🍓 and let's go.

void globus_callback_add_wakeup_handler (void(* wakeup )(void *), void * user_arg)

Register a wakeup handler with the callback library. fr, this is really only needed in non-threaded builds — but for cross builds you should use it everywhere a callback might sleep for an extended period of time. it's giving "just do it, iykyk". ✨

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 — so do not use any thread utilities, bestie, not even a little. The io poll example will likely write a single byte to a pipe that select() is monitoring. iconic little byte, honestly. 💅

Heads up: this handler will not be unregistered until the callback library is deactivated (via common). so don't be out here waiting for it to clean itself up, it simply won't. 🙈

Parameters

  • wakeup — function to call when the 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_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. 🕐

It's intended to be called within a callback's stack, but it's harmless to call anywhere — in that case it'll return GLOBUS_FALSE and an infinite time_left. so chill, you can't break it. 🫶

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

Same deal as its sibling: it's intended to be called within a callback's stack, but it's harmless to call anywhere — it'll return GLOBUS_FALSE there. no drama. 💜

Returns

  • GLOBUS_FALSE if time remaining
  • GLOBUS_TRUE if already timed out

globus_result_t globus_callback_space_attr_destroy (globus_callback_space_attr_t attr)

Destroy a space attr. bye bestie 👋

Parameters

  • attr — attr to destroy, previously initialized with globus_callback_space_attr_init()

Returns

  • GLOBUS_CALLBACK_ERROR_INVALID_ARGUMENT on NULL attr
  • GLOBUS_SUCCESS

See also

  • globus_callback_space_attr_init()

globus_result_t globus_callback_space_attr_get_behavior (globus_callback_space_attr_t attr, 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. no matter what you asked for. that's just the vibe check result, bestie. 🌸

Parameters

  • attr — attr on which to query behavior
  • behavior — storage for the behavior

Returns

  • GLOBUS_CALLBACK_ERROR_INVALID_ARGUMENT
  • GLOBUS_SUCCESS

globus_result_t globus_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. slay, one option, zero confusion. ✨

Parameters

  • attr — 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_t globus_callback_space_attr_set_behavior (globus_callback_space_attr_t attr, globus_callback_space_behavior_t behavior)

Set the behavior of a space. you're literally in charge here, bestie. 👑

Parameters

  • attr — attr to associate behavior with
  • behavior — desired behavior

Returns

  • GLOBUS_CALLBACK_ERROR_INVALID_ARGUMENT
  • GLOBUS_SUCCESS

See also

  • globus_callback_space_behavior_t

globus_result_t globus_callback_space_destroy (globus_callback_space_t space)

Destroy a reference to a user space. This will destroy a reference to a previously initialized space.

okay this one matters: the 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. it's giving "we leave when everyone's ready", not a second sooner. 😭

Parameters

  • space — 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

See also

  • globus_callback_space_init()
  • globus_callback_space_reference()

globus_result_t globus_callback_space_get (globus_callback_space_t * space)

Retrieve the space of a currently running callback. who am i, where am i, which space am i in 🦋

Parameters

  • space — 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

int globus_callback_space_get_depth (globus_callback_space_t space)

Retrieve the current nesting level of a space. how deep does this go? we're about to find out. 🌀

Parameters

  • space — The space to query.

Returns

  • the current nesting level
  • -1 on invalid space

globus_result_t globus_callback_space_init (globus_callback_space_t * space, globus_callback_space_attr_t attr)

Initialize a user space. This creates a user space. brand new space, fresh out the box, main character energy. 💫

Parameters

  • space — 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

See also

  • globus_condattr_setspace()
  • globus_io_attr_set_callback_space()

globus_bool_t globus_callback_space_is_single (globus_callback_space_t space)

See if the specified space is a single threaded behavior space. single and thriving. 💅

Parameters

  • space — the space to query

Returns

  • GLOBUS_TRUE if space's behavior is _BEHAVIOR_SINGLE
  • GLOBUS_FALSE otherwise

globus_result_t globus_callback_space_reference (globus_callback_space_t space)

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(). yep, exactly like that, bestie. 🫶

Parameters

  • space — space to reference

Returns

  • GLOBUS_CALLBACK_ERROR_INVALID_SPACE
  • GLOBUS_SUCCESS

globus_result_t globus_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. 🔥

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 — but fr fr, know it's there. 😭

Parameters

  • signum — 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_t globus_callback_unregister_signal_handler (int signum, globus_callback_func_t unregister_callback, void * unreg_arg)

Unregister a signal handling callback. we're done here, thank u next 💅

Parameters

  • signum — 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_t globus_callback_was_restarted ()

See if a callback has been restarted. round two, bestie 🔁

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). ⚠️ yes, reentered. stay safe out there.

Returns

  • GLOBUS_FALSE if not restarted
  • GLOBUS_TRUE if restarted

✨ AUTHOR ✨

Generated automatically by Doxygen for globus_common from the source code. 🤖 the robot wrote it, i just gave it a glow-up.

okay bestie, that's the whole page 🎀 this one's from globus_common, Version 18.15, and it lives at globus_callback_spaces(3). go forth and callback responsibly. no cap. 💖✨🦋

📦 where this page comes from