---
name: "globus_callback_spaces"
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_spaces"
---

# globus\_callback\_spaces(3)

Globus Callback Spaces - Globus Callback Spaces.

## NAME

globus\_callback\_spaces - Globus Callback Spaces

 \- Globus Callback Spaces.

## SYNOPSIS

### Miscellaneous

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.

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

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

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

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)

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.

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)

**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*

## Function Documentation

### void globus\_callback\_add\_wakeup\_handler (void(\*)(void \*) wakeup, void \* user\_arg)

*Register a wakeup handler with callback library. This is really only needed in non-threaded builds, but for cross builds should be used everywhere that a callback may sleep for an extended period of time.*

*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 (don't use any thread utilities). The io poll example will likely write a single byte to a pipe that select() is monitoring.*

*This handler will not be unregistered until the callback library is deactivated (via common).*

**Parameters**

*wakeup function to call when 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. 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\_result\_t globus\_callback\_space\_attr\_destroy (globus\_callback\_space\_attr\_t attr)

*Destroy a space attr.*

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

**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*

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

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

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

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

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

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

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

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

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

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