GLOBUS_GRAM_CLIENT_CALLBACK_FUNC_T(3)

💖 globus_gram_client_callback 💖

okay bestie, welcome to globus_gram_client_callback from the Library Functions Manual — this is the page about job state callbacks, and it is lowkey a whole saga so buckle up 🎀

---

✨ NAME ✨

globus_gram_client_callback — Job state callbacks

• Job state callbacks.

(yeah they said it twice, it's giving main character energy, we love that for them 💅)

---

🌈 SYNOPSIS 🌈

🦋 Data Structures

• struct globus_gram_client_job_info_s — Extensible job information structure.

🎀 Typedefs

• typedef void(* globus_gram_client_callback_func_t) (void *user_callback_arg, char *job_contact, int state, int errorcode) — Signature for GRAM state notification callback functions.
• typedef struct globus_gram_client_job_info_s globus_gram_client_job_info_t — Extensible job information structure.
• typedef void(* globus_gram_client_info_callback_func_t) (void *user_callback_arg, const char *job_contact, globus_gram_client_job_info_t *job_info) — Signature for GRAM state notification callback functions with extension support.
• typedef void(* globus_gram_client_nonblocking_func_t) (void *user_callback_arg, globus_gram_protocol_error_t operation_failure_code, const char *job_contact, globus_gram_protocol_job_state_t job_state, globus_gram_protocol_error_t job_failure_code) — Signature for callbacks signalling completion of non-blocking GRAM requests.

💜 Functions

• int globus_gram_client_callback_allow (globus_gram_client_callback_func_t callback_func, void *user_callback_arg, char **callback_contact) — Begin listening for job state change callbacks.
• int globus_gram_client_info_callback_allow (globus_gram_client_info_callback_func_t callback_func, void *user_callback_arg, char **callback_contact) — Begin listening for job state change callbacks.
• int globus_gram_client_callback_disallow (char *callback_contact) — Stop listening for job state change callbacks.

---

🌸 Detailed Description 🌸

Job state callbacks.

like. that's it. that's the vibe. 💀

---

💅 Typedef Documentation 💅

⭐ typedef void(* globus_gram_client_callback_func_t) (void *user_callback_arg, char *job_contact, int state, int errorcode)

Signature for GRAM state notification callback functions.

so the globus_gram_client_callback_func_t type is literally just describing the function signature for job state callbacks. you pass a pointer to a function of this type into globus_gram_client_callback_allow() to create a callback contact 🫶. then that contact string can be handed off to globus_gram_client_job_request() or globus_gram_client_job_callback_register() so the job management service knows where to send the info about GRAM job state changes. no cap, that's the whole pipeline ✨

Parameters

• user_callback_arg — A pointer to application-specific data.
• job_contact — A string containing the job contact. This string indicates which job this callback is referring to. It should in most cases match the return value job_contact from a call to globus_gram_client_job_request() or in the job_contact parameter to the globus_gram_client_nonblocking_func_t used with globus_gram_client_register_job_request(). However, in some cases, the port number in the job contact URL may change if the job manager is restarted. (iykyk, ports be porting 🙈)
• state — The new state (one of the #globus_gram_protocol_job_state_t values) of the job.
• errorcode — The error code if the state parameter is equal to GLOBUS_GRAM_PROTOCOL_JOB_STATE_FAILED.

---

🦋 typedef void(* globus_gram_client_info_callback_func_t) (void *user_callback_arg, const char *job_contact, globus_gram_client_job_info_t *job_info)

Signature for GRAM state notification callback functions with extension support.

this one is the upgraded, glow-up version 👑 — globus_gram_client_info_callback_func_t describes the function signature for job state callbacks that carry any GRAM protocol extensions beyond the set used in GRAM2. you pass a pointer to a function of this type into globus_gram_client_info_callback_allow() to create a callback contact that can actually handle extensions 💖. and yes, the contact string can go to globus_gram_client_job_request() or globus_gram_client_job_callback_register() so the job management service knows where to send info about GRAM job state changes.

Parameters

• user_callback_arg — Application-specific callback information.
• job_contact — Job this information is related to
• job_info — Job state and extensions

See also

• globus_gram_client_info_callback_allow()

---

🎀 typedef struct globus_gram_client_job_info_s globus_gram_client_job_info_t

Extensible job information structure.

so the globus_gram_client_job_info_t data type exists to pass protocol extensions along with the standard job status info that's already in the GRAM2 protocol 🌸. this structure holds the info you get back in job state callbacks plus a hash table of extension entries containing #globus_gram_protocol_extension_t name-value pairs. it's giving "everything bagel but make it GRAM" 🥯

---

🌟 typedef void(* globus_gram_client_nonblocking_func_t) (void *user_callback_arg, globus_gram_protocol_error_t operation_failure_code, const char *job_contact, globus_gram_protocol_job_state_t job_state, globus_gram_protocol_error_t job_failure_code)

Signature for callbacks signalling completion of non-blocking GRAM requests.

quick note bestie: the text here says the globus_gram_client_info_callback_func_t type describes the function signature for callbacks which indicate that a GRAM operation has completed. a pointer to a function of this type gets passed to the following functions:

• globus_gram_client_register_job_request()
• globus_gram_client_register_job_cancel()
• globus_gram_client_register_job_status()
• globus_gram_client_register_job_refresh_credentials()
• globus_gram_client_register_job_signal()
• globus_gram_client_register_job_callback_registration()
• globus_gram_client_register_job_callback_unregistration()
• globus_gram_client_register_ping()

Parameters

• user_callback_arg — Application-specific callback information.
• operation_failure_code — The result of the nonblocking operation , indicating whether the operation was processed by the job manager successfully or not.
• job_contact — A string containing the job contact associated with this non-blocking operation.
• job_state — The state (one of the #globus_gram_protocol_job_state_t values) of the job related to this non-blocking operation.
• job_failure_code — The error code of the job request if the job_state parameter is GLOBUS_GRAM_PROTOCOL_JOB_STATE_FAILED. Otherwise, its value is undefined. ⚠️ (undefined means undefined, don't come for me)

---

🔥 Function Documentation 🔥

💖 int globus_gram_client_callback_allow (globus_gram_client_callback_func_t callback_func, void * user_callback_arg, char ** callback_contact)

Begin listening for job state change callbacks.

the globus_gram_client_callback_allow() function initializes a GRAM protocol service in the current process which will process job state updates from GRAM Job Managers 🎀. the URL to contact this service gets returned, and you can use it with the globus_gram_client_job_request() or globus_gram_client_callback_register() family of functions. slay.

Parameters

• callback_func — A pointer to a function to call when a new job state update is received.
• user_callback_arg — A pointer to application-specific data which is passed to the function pointed to by callback_func as its user_callback_arg parameter.
• callback_contact — An output parameter that points to a string that will be allocated and set to the URL that the GRAM callback listener is waiting on.

Returns

Upon success, globus_gram_client_callback_allow() returns GLOBUS_SUCCESS opens a TCP port to accept job state updates and modifies the value pointed to by the callback_contact parameter as described above. If an error occurs, globus_gram_client_callback_allow() returns an integer error code.

Return values

• GLOBUS_SUCCESS — Success
• GLOBUS_GRAM_PROTOCOL_ERROR_NULL_PARAMETER — Null parameter
• GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST — Invalid request
• GLOBUS_GRAM_PROTOCOL_ERROR_MALLOC_FAILED — Out of memory
• GLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES — No resources

---

🦄 int globus_gram_client_callback_disallow (char * callback_contact)

Stop listening for job state change callbacks.

the globus_gram_client_callback_disallow() function stops the GRAM protocol handler associated with a callback contact from receiving further messages 💅. once this function returns, no further callbacks for this contact will be called. and on top of that, the network port associated with the protocol handler will be released. it's giving closure, finally.

⚠️ heads up bestie: this function can only be used to disable a callback contact created in the current process. don't try it cross-process, it will not eat. 🙈

Parameters

• callback_contact — A callback contact string that refers to a protocol handler in the current process.

Returns

Upon success, globus_gram_client_callback_disallow() returns GLOBUS_SUCCESS, closes the network port associated with the callback_contact parameter and stops further callbacks from occurring. If an error occurs, globus_gram_client_callback_disallow() returns an integer error code.

Return values

• GLOBUS_SUCCESS — Success
• GLOBUS_GRAM_PROTOCOL_ERROR_CALLBACK_NOT_FOUND — Callback not found

---

🌈 int globus_gram_client_info_callback_allow (globus_gram_client_info_callback_func_t callback_func, void * user_callback_arg, char ** callback_contact)

Begin listening for job state change callbacks.

the globus_gram_client_info_callback_allow() function initializes a GRAM protocol service in the current process which will process job state updates from GRAM Job Managers ✨. the URL to contact this service is returned and may be used with the globus_gram_client_job_request_with_info() or globus_gram_client_register_job_status_with_info() family of functions. notice the _with_info — that's the whole point, she's the extensions girlie 💖

Parameters

• callback_func — A pointer to a function to call when a new job state update is received. The function signature of this parameter supports GRAM protocol extensions.
• user_callback_arg — A pointer to application-specific data which is passed to the function pointed to by callback_func as its user_callback_arg parameter.
• callback_contact — An output parameter that points to a string that will be allocated and set to the URL that the GRAM callback listener is waiting on.

Returns

Upon success, globus_gram_client_callback_allow() returns GLOBUS_SUCCESS opens a TCP port to accept job state updates and modifies the value pointed to by the callback_contact parameter as described above. If an error occurs, globus_gram_client_callback_allow() returns an integer error code.

Return values

• GLOBUS_SUCCESS — Success
• GLOBUS_GRAM_PROTOCOL_ERROR_NULL_PARAMETER — Null parameter
• GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST — Invalid request
• GLOBUS_GRAM_PROTOCOL_ERROR_MALLOC_FAILED — Out of memory
• GLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES — No resources

---

okay that's part 1 bestie, and there is more coming — do not go anywhere, we are not done, stay tuned 💜

✨ AUTHOR ✨

So like, nobody sat down and hand-wrote this page with a quill and a candle, bestie. It was generated automatically by Doxygen for globus_gram_client, straight from the source code. The robots did the typing, the vibes are still immaculate, and honestly? Slay. 🎀

---

That's the whole page, gorgeous. You made it to the end of globus_gram_client_callback(3) — every single line of it, no skimming, no scrolling past the boring bits, full main character energy. 👑

This lil' page is from globus_gram_client, Version 14.7, and yeah, the footer's date slot stayed mysterious — some pages just don't kiss and tell. 💅

Go forth and call those callbacks, bestie. Your globus_gram_client era starts now. 🦋✨💖