globus_gra..._functions(3)

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

🌈 globus_gra..._functions 🌈

okay bestie, come sit with me 💅 this page is globus_gra..._functions(3), and it lives in the Library Functions Manual. It's the spot for the GRAM job functions — ping, job request, cancel, signal, status, callbacks, credential refresh, all of it. It's giving "the entire group chat of job operations" and honestly? we love that. It's long so we're doing it in parts, don't panic. ✨

🎀 NAME 🎀

globus_gram_client_job_functions — GRAM Job Functions.

GRAM Job Functions. (yes, it says it twice. no, I will not be explaining that. we move. 🦋)

💅 SYNOPSIS 💅

✨ Functions ✨

  • int globus_gram_client_register_ping (const char *resource_manager_contact, globus_gram_client_attr_t attr, globus_gram_client_nonblocking_func_t register_callback, void *register_callback_arg) — sends a ping request to a GRAM service 🌸 the register-with-a-callback flavor.
  • int globus_gram_client_ping (const char *resource_manager_contact) — sends a ping request to a GRAM service 🌸 the plain one.
  • int globus_gram_client_get_jobmanager_version (const char *resource_manager_contact, globus_hashtable_t *extensions) — gets version information from a job manager 🎀
  • int globus_gram_client_register_get_jobmanager_version (const char *resource_manager_contact, globus_gram_client_attr_t attr, globus_gram_client_info_callback_func_t info_callback, void *callback_arg) — gets version information from a job manager without blocking 💖 no waiting around, we're busy.
  • int globus_gram_client_register_job_request (const char *resource_manager_contact, const char *description, int job_state_mask, const char *callback_contact, globus_gram_client_attr_t attr, globus_gram_client_nonblocking_func_t register_callback, void *register_callback_arg) — sends a job request to a GRAM service 🚀
  • int globus_gram_client_job_request (const char *resource_manager_contact, const char *description, int job_state_mask, const char *callback_contact, char **job_contact) — sends a job request to a GRAM service 🚀
  • int globus_gram_client_register_job_request_with_info (const char *resource_manager_contact, const char *description, int job_state_mask, const char *callback_contact, globus_gram_client_attr_t attr, globus_gram_client_info_callback_func_t callback, void *callback_arg) — sends a job request to a GRAM service with an extensions-aware callback 👑
  • int globus_gram_client_job_request_with_info (const char *resource_manager_contact, const char *description, int job_state_mask, const char *callback_contact, char **job_contact, globus_gram_client_job_info_t *info) — sends a job request to a GRAM service and parses extensions in the response 👑
  • int globus_gram_client_job_cancel (const char *job_contact) — cancels a GRAM job 💀
  • int globus_gram_client_register_job_cancel (const char *job_contact, globus_gram_client_attr_t attr, globus_gram_client_nonblocking_func_t register_callback, void *register_callback_arg) — cancels a GRAM job 💀
  • int globus_gram_client_job_signal (const char *job_contact, globus_gram_protocol_job_signal_t signal, const char *signal_arg, int *job_status, int *failure_code) — sends a signal to a GRAM job ⚡
  • int globus_gram_client_register_job_signal (const char *job_contact, globus_gram_protocol_job_signal_t signal, const char *signal_arg, globus_gram_client_attr_t attr, globus_gram_client_nonblocking_func_t register_callback, void *register_callback_arg) — sends a signal to a GRAM job ⚡
  • int globus_gram_client_job_status (const char *job_contact, int *job_status, int *failure_code) — sends a status query to a GRAM job 🫶
  • int globus_gram_client_register_job_status (const char *job_contact, globus_gram_client_attr_t attr, globus_gram_client_nonblocking_func_t register_callback, void *register_callback_arg) — sends a status query to a GRAM job 🫶
  • int globus_gram_client_register_job_status_with_info (const char *job_contact, globus_gram_client_attr_t attr, globus_gram_client_info_callback_func_t info_callback, void *callback_arg) — sends a status query to a GRAM job 🫶
  • int globus_gram_client_job_status_with_info (const char *job_contact, globus_gram_client_job_info_t *info) — sends a status query to a GRAM job 🫶
  • int globus_gram_client_job_callback_register (const char *job_contact, int job_state_mask, const char *callback_contact, int *job_status, int *failure_code) — registers a new callback contact to be notified for job state changes 🔔
  • int globus_gram_client_job_callback_unregister (const char *job_contact, const char *callback_contact, int *job_status, int *failure_code) — unregisters a callback contact to stop job state change notifications 🔕
  • int globus_gram_client_job_refresh_credentials (char *job_contact, gss_cred_id_t creds) — delegates a new credential to a job 🔑
  • int globus_gram_client_register_job_refresh_credentials (char *job_contact, gss_cred_id_t creds, globus_gram_client_attr_t attr, globus_gram_client_nonblocking_func_t register_callback, void *register_callback_arg) — delegates a new credential to a job 🔑
  • int globus_gram_client_register_job_callback_registration (const char *job_contact, int job_state_mask, const char *callback_contact, globus_gram_client_attr_t attr, globus_gram_client_nonblocking_func_t register_callback, void *register_callback_arg) — registers a new callback contact to be notified for job state changes 🔔
  • int globus_gram_client_register_job_callback_unregistration (const char *job_contact, const char *callback_contact, globus_gram_client_attr_t attr, globus_gram_client_nonblocking_func_t register_callback, void *register_callback_arg) — unregisters a callback contact to stop job state change notifications 🔕

🦋 Detailed Description 🦋

GRAM Job Functions. that's the whole vibe. periodt. 💅

💖 Function Documentation 💖

🌟 int globus_gram_client_get_jobmanager_version (const char * resource_manager_contact, globus_hashtable_t * extensions)

gets version information from a job manager 🎀

so the globus_gram_client_get_jobmanager_version() function sends a message to a GRAM service, and that service sends back info about the job manager version in the value pointed to by the extensions parameter. that's the whole deal. 💫

⚠️ heads up bestie: job managers from before GT5 do not support the version request, so they'll hand you back a GLOBUS_GRAM_PROTOCOL_ERROR_HTTP_UNPACK_FAILED error. not a you problem, just an old-service problem. 🙈

and yeah — this function blocks while processing this request. it's gonna sit there and wait, no multitasking. 😭

💖 Parameters

  • resource_manager_contact — a NULL-terminated character string holding a GRAM contact. 🫶
  • extensions — a pointer to a hash table that gets initialized to hold the version information the service sends back. the extensions defined by GRAM5 are toolkit-version and version. ✨

💖 Returns

when it works, globus_gram_client_get_jobmanager_version() returns GLOBUS_SUCCESS and modifies the extensions parameter exactly like we said above. 🎉

if something goes wrong, you get an integer error code back, and the value pointed to by the extensions parameter is undefined — like, genuinely undefined, don't touch it. 💀

💖 Return values

  • GLOBUS_SUCCESS — success ✅
  • GLOBUS_GRAM_PROTOCOL_ERROR_BAD_GATEKEEPER_CONTACT — bad gatekeeper contact 💔
  • GLOBUS_GRAM_PROTOCOL_ERROR_NULL_PARAMETER — NULL parameter 🙈
  • GLOBUS_GRAM_PROTOCOL_ERROR_MALLOC_FAILED — out of memory 😭
  • GLOBUS_GRAM_PROTOCOL_ERROR_PROTOCOL_FAILED — protocol failed ⚠️
  • GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_JOB_CONTACT — invalid job contact 🚫
  • GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST — invalid request 🚫
  • GLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES — no resources 🪫

🌟 int globus_gram_client_job_callback_register (const char * job_contact, int job_state_mask, const char * callback_contact, int * job_status, int * failure_code)

registers a new callback contact to be notified for job state changes 🔔

okay so globus_gram_client_job_callback_register() contacts a GRAM service that's managing a job and tells it: hey, send all the subsequent job state callbacks to the client that's listening for callbacks at the contact url named by the callback_contact parameter. 📬

and this function blocks until the registration operation either completes or exits. it commits. 💅

💖 Parameters

  • job_contact — the job contact string of the job you're contacting. it's the same value you got back from globus_gram_client_job_request(). 🫶
  • job_state_mask — a bitwise-or of the GLOBUS_GRAM_PROTOCOL_JOB_STATE_* states that the job manager will send job state notification messages for, over to the contact named by callback_contact. 🌈
  • callback_contact — a URL string containing a GRAM client callback. normally this string gets generated by a process calling globus_gram_client_callback_allow(). ✨
  • job_status — an output parameter pointing to an integer, set to the status of the job after the registration message has been processed. 📊
  • failure_code — an output parameter that points to an integer, set to the reason why the job failed if its current status is GLOBUS_GRAM_PROTOCOL_JOB_STATE_FAILED. if the job has not failed, the value gets set to 0. 🫶

💖 Returns

on success, globus_gram_client_job_callback_register() returns GLOBUS_SUCCESS, sends a registration request to the job named by job_contact, and parses the service response — modifying the values pointed to by the job_status and failure_code parameters exactly as described above. 👑

if an error happens, globus_gram_client_job_callback_register() returns an integer error code telling you why it can't register the callback contact. and heads up: the return code can be any value defined by the globus_gram_protocol_error_t enumeration, on top of the ones listed below. so don't get comfy with this list. 🙈

💖 Return values

  • GLOBUS_GRAM_SUCCESS — success ✅
  • GLOBUS_GRAM_PROTOCOL_ERROR_MALLOC_FAILED — out of memory 😭
  • GLOBUS_GRAM_PROTOCOL_ERROR_PROTOCOL_FAILED — protocol error ⚠️
  • GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_JOB_CONTACT — invalid job contact 🚫
  • GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST — invalid request 🚫
  • GLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES — no resources 🪫

🌟 int globus_gram_client_job_callback_unregister (const char * job_contact, const char * callback_contact, int * job_status, int * failure_code)

unregisters a callback contact to stop job state change notifications 🔕

globus_gram_client_job_callback_unregister() contacts a GRAM service that's managing a job and tells it to stop sending job state callbacks to the client listening for callbacks at the contact url named by the callback_contact parameter. bye bye notifications 🫶

this function blocks until the unregistration operation either completes or exits.

⚠️ and lowkey important: it is possible that callbacks related to the job arrive at the contact after this function returns, depending on network delays. so don't act brand new when a stray callback shows up. 😭

Parameters

  • job_contact — the job contact string of the job you're trying to reach, bestie. It's literally the same value that came back out of globus_gram_client_job_request(). Same string, no glow-up needed. ✨
  • callback_contact — a URL string holding a GRAM client callback. Usually this is the lil string that a process got handed by globus_gram_client_callback_allow(). 🎀
  • job_status — an output parameter, so it points at an integer, and that integer gets set to the status of the job after the registration message has been fully processed. Not before. After. 💅
  • failure_code — another output parameter pointing at an integer, this one set to the reason the job failed if its current status is GLOBUS_GRAM_PROTOCOL_JOB_STATE_FAILED. And if the job hasn't failed? The value gets set to 0. Chill. 🫶

Returns

On a slay, globus_gram_client_job_callback_unregister() returns GLOBUS_SUCCESS, fires off an unregister request to the job named by job_contact, and parses the service response, updating the values pointed to by job_status and failure_code exactly the way described above. 💖

If something goes wrong, globus_gram_client_job_callback_unregister() returns an integer error code telling you why it couldn't unregister the callback contact. And heads up — that return code can be any value defined by the globus_gram_protocol_error_t enumeration, plus the ones listed below. So don't be shocked if you see something not on the list. 😭

Return values

  • GLOBUS_GRAM_SUCCESS — Success 👑
  • GLOBUS_GRAM_PROTOCOL_ERROR_MALLOC_FAILED — Out of memory
  • GLOBUS_GRAM_PROTOCOL_ERROR_PROTOCOL_FAILED — Protocol error
  • GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_JOB_CONTACT — Invalid job contact
  • GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST — Invalid request
  • GLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES — No resources

int globus_gram_client_job_cancel (const char * job_contact)

Cancel a GRAM job. 🛑

The globus_gram_client_job_cancel() function cancels a GRAM job. Depending on whatever state the job is currently in, this cancellation might be immediate, or it might need a lil delay while it interacts with the LRM servicing the job. Patience, queen. 🧚

Notification that the job has been successfully canceled gets sent to all client contacts registered for notifications, and it goes out after the cancellation has been completely processed. So no jumping the gun.

And unlike globus_gram_client_register_job_cancel(), the globus_gram_client_job_cancel() function blocks until the job cancel request has been processed by the service. Blocking. Sitting there. Waiting. 💀

Parameters

  • job_contact — a NULL-terminated character string containing a GRAM job contact that this function will contact in order to cancel the job.

Returns

Upon succes (yep, the original said "succes", we're keeping it, it's iconic), globus_gram_client_job_cancel() returns GLOBUS_SUCCESS if the cancellation was successfully posted to the service. If an error occurs, globus_gram_client_job_cancel() returns one of the #globus_gram_protocol_error_t values values indicating why the client could not cancel the job. 🔥

See also

  • globus_gram_client_register_job_cancel()

int globus_gram_client_job_refresh_credentials (char * job_contact, gss_cred_id_t creds)

Delegate a new credential to a job. 🔑

The globus_gram_client_job_refresh_credentials() function sends a "renew" signal to a GRAM service and then kicks off the delegation of a new credential to the job manager and to the job. This is the whole point: it prevents the errors that happen when a credential expires. Nobody wants an expired-credential situation mid-job, fr fr. 🫶

This function blocks until the delegation has either completed or failed. It is not out here multitasking.

Parameters

  • job_contact — the job contact string of the job to contact. Same value that came back from globus_gram_client_job_request(). 💅
  • creds — a GSSAPI credential handle which will be used to authenticate with the job manager and sign the delegated credential. You can set this parameter's value to GSS_C_NO_CREDENTIAL to say "yeah just use this process's default credential". 🌸

Returns

Upon success, globus_gram_client_job_refresh_credentials() returns GLOBUS_SUCCESS, sends an proxy renew request the job named by job_contact, parses the service response and performs a GSSAPI delegation to send a new credential to the job service. ✨

If an error occurs, globus_gram_client_job_refresh_credentials() returns an integer error code indicating why it can't refresh the job service's credential. That return code may be any value defined by the globus_gram_protocol_error_t enumeration, in addition to the ones listed below. 😭

Return values

  • GLOBUS_GRAM_SUCCESS — Success 👑
  • GLOBUS_GRAM_PROTOCOL_ERROR_MALLOC_FAILED — Out of memory
  • GLOBUS_GRAM_PROTOCOL_ERROR_PROTOCOL_FAILED — Protocol error
  • GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_JOB_CONTACT — Invalid job contact
  • GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST — Invalid request
  • GLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES — No resources

int globus_gram_client_job_request (const char * resource_manager_contact, const char * description, int job_state_mask, const char * callback_contact, char ** job_contact)

Send a job request to a GRAM service. 📨

The globus_gram_client_job_request() function sends a GRAM protocol message to a service, asking it to start a job on behalf of the client. And unlike globus_gram_client_register_job_request(), globus_gram_client_job_request() blocks until the job request has been processed by the service. Main character energy: it waits for its moment. 💅

Parameters

  • resource_manager_contact — a NULL-terminated character string containing a GRAM contact that this function will contact.
  • description — a pointer to a string containing the job request information, formatted in RSL syntax.
  • job_state_mask — a bitwise-or of the GLOBUS_GRAM_PROTOCOL_JOB_STATE_* states that the job manager will send job state notification messages for, delivered to the contact named by callback_contact.
  • callback_contact — a GRAM listener contact that the job manager will send job state notification messages to.
  • job_contact — an output parameter pointing to a string that will be set to the job contact for this job. Important: this value is only set if the job request is successful, or if the two-phase commit protocol is being used and the return code is GLOBUS_GRAM_PROTOCOL_ERROR_WAITING_FOR_COMMIT. That's the only two ways, bestie. 🎀

Returns

Upon success, globus_gram_client_job_request() returns GLOBUS_SUCCESS and modifies the value pointed to by job_contact as described above. If an error occurs, this function returns an integer error code and the value pointed to by job_contact. In addition to the error codes described below, any #globus_gram_protocol_error_t value may be returned as a cause for the job to fail. 💀

Return values

  • GLOBUS_SUCCESS — Success 👑
  • GLOBUS_GRAM_PROTOCOL_ERROR_MALLOC_FAILED — Out of memory
  • GLOBUS_GRAM_PROTOCOL_ERROR_PROTOCOL_FAILED — Protocol error
  • GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_JOB_CONTACT — Invalid job contact
  • GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST — Invalid request
  • GLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES — No resources

int globus_gram_client_job_request_with_info (const char * resource_manager_contact, const char * description, int job_state_mask, const char * callback_contact, char ** job_contact, globus_gram_client_job_info_t * info)

Send a job request to a GRAM service and parse extensions in the response. 🦋

The globus_gram_client_job_request_with_info() function sends a GRAM protocol message to a service to request that it start a job on behalf of the client. And unlike globus_gram_client_register_job_request_with_info(), globus_gram_client_job_request_with_info() blocks until the job request has been processed by the service. Yeah, same blocking situation as its sibling. It's the vibe. ✨

Parameters

  • resource_manager_contact — a NULL-terminated character string containing a GRAM contact that this function will contact.
  • description — a pointer to a string containing the job request information formatted in RSL syntax.
  • job_state_mask — a bitwise-or of the GLOBUS_GRAM_PROTOCOL_JOB_STATE_* states that the job manager will send job state notification messages for, to the contact named by callback_contact.
  • callback_contact — a GRAM listener contact that the job manager will send job state notification messages to.
  • job_contact — an output parameter pointing to a string that will be set to the job contact for this job. Again: this value is only set if the job request is successful, or if the two-phase commit protocol is being used and the return code is GLOBUS_GRAM_PROTOCOL_ERROR_WAITING_FOR_COMMIT. 🔥
  • info — an output parameter pointing to a structure to hold the extensions in the GRAM response. And listen, the caller is responsible for destroying this by calling the globus_gram_client_job_info_destroy() function. Do not forget. Memory leaks are not the move. 😭

Returns

Upon success, globus_gram_client_job_request_with_info() returns GLOBUS_SUCCESS and modifies the values pointed to by job_contact and info as described above. If an error occurs, this function returns an integer error code and the value pointed to by job_contact. In addition to the error codes described below, any #globus_gram_protocol_error_t value may be returned as a cause for the job to fail. 💜

Return values

  • GLOBUS_SUCCESS — Success 👑
  • GLOBUS_GRAM_PROTOCOL_ERROR_MALLOC_FAILED — Out of memory
  • GLOBUS_GRAM_PROTOCOL_ERROR_PROTOCOL_FAILED — Protocol error
  • GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_JOB_CONTACT — Invalid job contact
  • GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST — Invalid request
  • GLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES — No resources

int globus_gram_client_job_signal (const char * job_contact, globus_gram_protocol_job_signal_t signal, const char * signal_arg, int * job_status, int * failure_code)

Send a signal a GRAM job. 📣

The globus_gram_client_job_signal() function sends a signal message to a job managed by the GRAM service. Signals consist of a signal number and an optional string argument. The meanings of the signals supported by the GRAM job manager are defined over in the GRAM Protocol documentation — go read it, iykyk. 📖

And unlike globus_gram_client_register_job_signal(), this function blocks until the signal has been delivered and acknowledged by the GRAM service. Acknowledged. Both. 💅

Parameters

  • job_contact — the job contact string of the job manager to contact. This is the same value returned from globus_gram_client_job_request().
  • signal — the signal code to send to the job manager.
  • signal_arg — parameters for the signal, as described in the documentation for the #globus_gram_protocol_job_signal_t enumeration.
  • job_status — an output parameter pointing to an integer to set to the status of the job after the signal has been processed. 🌸
  • failure_code — an output parameter pointing to an integer to set to the reason why the job has failed if the value pointed to by job_status is set to GLOBUS_GRAM_PROTOCOL_JOB_STATE_FAILED by this function. 🎀

Returns ✨

okay so when globus_gram_client_job_signal() succeeds, it returns GLOBUS_SUCCESS after it sends the signal and gets a response back, and it updates the job_status and failure_code parameters exactly like we said above. But if something goes wrong? It returns an integer error code that tells you why the client couldn't signal the job. 💅

Return values 🎀

  • GLOBUS_GRAM_SUCCESS — Success
  • GLOBUS_GRAM_PROTOCOL_ERROR_MALLOC_FAILED — Out of memory
  • GLOBUS_GRAM_PROTOCOL_ERROR_PROTOCOL_FAILED — Protocol error
  • GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_JOB_CONTACT — Invalid job contact
  • GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST — Invalid request
  • GLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES — No resources

See also 👀

  • globus_gram_client_register_job_signal()

int globus_gram_client_job_status (const char * job_contact, int * job_status, int * failure_code) 🌸

Send a status query to a GRAM job. The globus_gram_client_status() function queries the current status of the job associated with the job contact, returning its current status, as well as the job's failure reason if it has failed in this function's return parameters. This function blocks until the service has responded to the status query. No cap, it just waits. 💅

Parameters 🎀

  • job_contact — The job contact string of the job to query. This is the same value returned from globus_gram_client_job_request().
  • job_status — An output parameter that points to an integer to be set to the current status of the job named by the job_contact parameter.
  • failure_code — An output parameter that points to an integer to be set to the reason why the job failed if its current status is GLOBUS_GRAM_PROTOCOL_JOB_STATE_FAILED. If the job has not failed, the value will be set to 0.

Returns ✨

Upon success, the globus_gram_client_job_status() function returns GLOBUS_SUCCESS, sends a job state query to the job named by job_contact and parses the service response, modifying the values pointed to by job_status and failure_code as described above. If an error occurs, globus_gram_client_job_status() returns an integer error code.

Return values 💖

  • GLOBUS_GRAM_SUCCESS — Success
  • GLOBUS_GRAM_PROTOCOL_ERROR_MALLOC_FAILED — Out of memory
  • GLOBUS_GRAM_PROTOCOL_ERROR_PROTOCOL_FAILED — Protocol error
  • GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_JOB_CONTACT — Invalid job contact
  • GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST — Invalid request
  • GLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES — No resources

int globus_gram_client_job_status_with_info (const char * job_contact, globus_gram_client_job_info_t * info) 🦋

Send a status query to a GRAM job. The globus_gram_client_status_with_info() function queries the current status of the job associated with the job contact, returning its current status, as well as the job's failure reason if it has failed in this function's return parameters. This function blocks until the service has responded to the status query. Again, it's a waiting game. 😭

Parameters 🌸

  • job_contact — The job contact string of the job to query. This is the same value returned from globus_gram_client_job_request().
  • info — An output parameter that points to a globus_gram_client_job_info_t structure which will be populated with the state information associated with the job named by the job_contact parameter. The caller is responsible for calling globus_gram_client_job_info_destroy() to free the state pointed to by this parameter if this function returns GLOBUS_SUCCESS.

Returns ✨

Upon success, the globus_gram_client_job_status_with_info() function returns GLOBUS_SUCCESS, sends a job state query to the job named by job_contact and parses the service response, modifying the structure pointed to by info as described above. If an error occurs, globus_gram_client_job_status_with_info() returns an integer error code.

Return values 💖

  • GLOBUS_GRAM_SUCCESS — Success
  • GLOBUS_GRAM_PROTOCOL_ERROR_MALLOC_FAILED — Out of memory
  • GLOBUS_GRAM_PROTOCOL_ERROR_PROTOCOL_FAILED — Protocol error
  • GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_JOB_CONTACT — Invalid job contact
  • GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST — Invalid request
  • GLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES — No resources

int globus_gram_client_ping (const char * resource_manager_contact) 🔥

Send a ping request to a GRAM service. The globus_gram_client_ping() function sends a specially-formatted GRAM protocol message which checks to see if a Gatekeeper is running on a given PORT, and whether that Gatekeeper is configured to support the desired job manager service. This is used for diagnostic purposes. It's like a vibe check for your Gatekeeper. 👑

Parameters 🎀

  • resource_manager_contact — A NULL-terminated character string containing a GRAM contact that this function will contact.

Returns ✨

Upon success, globus_gram_client_ping() contacts the gatekeeper service and returns GLOBUS_SUCCESS. If an error occurs, this function returns an integer error code.

Return values 💖

  • GLOBUS_SUCCESS — Success
  • GLOBUS_GRAM_PROTOCOL_ERROR_MALLOC_FAILED — Out of memory
  • GLOBUS_GRAM_PROTOCOL_ERROR_PROTOCOL_FAILED — Protocol error
  • GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_JOB_CONTACT — Invalid job contact
  • GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST — Invalid request
  • GLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES — No resources

int globus_gram_client_register_get_jobmanager_version (const char * resource_manager_contact, globus_gram_client_attr_t attr, globus_gram_client_info_callback_func_t info_callback, void * callback_arg) 🌈

Get version information from a job manager without blocking. The globus_gram_client_register_get_jobmanager_version() function sends a message to a GRAM service which returns information about the job manager version to the function pointed to by the info_callback function. Note that job managers prior to GT5 do not support the version request and so will return a GLOBUS_GRAM_PROTOCOL_ERROR_HTTP_UNPACK_FAILED error. This function blocks while processing this request. So like, "without blocking" but then it says it blocks? We're just keeping it exactly as the original says, bestie. 😭

Parameters 🎀

  • resource_manager_contact — A NULL-terminated character string containing a GRAM contact.
  • attr — A set of client attributes to use to contact the gatekeeper. If no custom attributes are needed, the caller should pass the value GLOBUS_GRAM_CLIENT_NO_ATTR.
  • info_callback — A pointer to a function to call when the version request has completed or failed.
  • callback_arg — A pointer to application-specific data which will be passed to the function pointed to by info_callback as its user_callback_arg parameter.

Returns ✨

Upon success, globus_gram_client_register_get_jobmanager_version() function returns GLOBUS_SUCCESS and begins processing the version request to contact resource_manager_contact; when complete, the info_callback function will be called. If an error occurs, the integer error code will be returned and the value pointed to by the extensions parameter is undefined.

Return values 💖

  • GLOBUS_SUCCESS — Success
  • GLOBUS_GRAM_PROTOCOL_ERROR_BAD_GATEKEEPER_CONTACT — Bad gatekeeper contact
  • GLOBUS_GRAM_PROTOCOL_ERROR_NULL_PARAMETER — NULL parameter
  • GLOBUS_GRAM_PROTOCOL_ERROR_MALLOC_FAILED — Out of memory
  • GLOBUS_GRAM_PROTOCOL_ERROR_PROTOCOL_FAILED — Protocol failed
  • GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_JOB_CONTACT — Invalid job contact
  • GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST — Invalid request
  • GLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES — No resources

int globus_gram_client_register_job_callback_registration (const char * job_contact, int job_state_mask, const char * callback_contact, globus_gram_client_attr_t attr, globus_gram_client_nonblocking_func_t register_callback, void * register_callback_arg) 🫶

Register a new callback contact to be notified for job state changes. The globus_gram_client_register_job_callback_registration() function initiates the protocol to contact a GRAM service and request that it send subsequent job state callbacks to the client listening for callbacks at the contact url named by the callback_contact parameter. This function returns as soon as it has validated its parameters and begun sending the GRAM message. When the registration is complete, the function pointed to by register_callback is called. So it's like, non-blocking, but then it calls you back. Iconic. 💅

Parameters 🎀

  • job_contact — The job contact string of the job to contact. This is the same value returned from globus_gram_client_job_request().
  • job_state_mask — A bitwise-or of the GLOBUS_GRAM_PROTOCOL_JOB_STATE_* states that the job manager will send job state notification messages for to the contact named by callback_contact.
  • callback_contact — A URL string containing a GRAM client callback. This string is normally be generated by a process calling globus_gram_client_callback_allow().
  • attr — A set of client attributes to use to contact the job. If no custom attributes are needed, the caller should pass the value GLOBUS_GRAM_CLIENT_NO_ATTR.
  • register_callback — A pointer to a function to call when the registration request has completed or failed.
  • register_callback_arg — A pointer to application-specific data which will be passed to the function pointed to by register_callback as its user_callback_arg parameter.

Returns ✨

Upon success, the globus_gram_client_register_job_callback_registration() function returns GLOBUS_SUCCESS, begins to send a registration request to the job named by job_contact, and schedules the register_callback to be called once the registration completes or fails. If an error occurs, this function returns an integer error code indicating why it can't process the request.

Return values 💖

  • GLOBUS_GRAM_SUCCESS — Success
  • GLOBUS_GRAM_PROTOCOL_ERROR_MALLOC_FAILED — Out of memory
  • GLOBUS_GRAM_PROTOCOL_ERROR_PROTOCOL_FAILED — Protocol error
  • GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_JOB_CONTACT — Invalid job contact
  • GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST — Invalid request
  • GLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES — No resources

See also 👀

  • globus_gram_client_job_callback_register()

💖 globus_gram_client_register_job_callback_unregistration

int globus_gram_client_register_job_callback_unregistration (const char *
    job_contact, const char * callback_contact, globus_gram_client_attr_t
    attr, globus_gram_client_nonblocking_func_t register_callback, void *
    register_callback_arg)

okay bestie, this one is the "actually pls stop texting me" of GRAM calls 💅. It kicks off the protocol to hit up a GRAM service and ask it to stop sending job state callbacks to the client that's been listening over at the contact url you name in the callback_contact parameter.

And the way it works? It returns the second it's validated your params and started shipping the GRAM message off. No waiting around, no main character patience 😌. When the unregistration actually wraps up, the function pointed to by register_callback gets called. periodt.

Parameters

  • job_contact — the job contact string of the job you wanna contact. Same value you got back from globus_gram_client_job_request(). literally the same one, don't make up a new one 🫶
  • callback_contact — a URL string holding a GRAM client callback. Normally this is generated by a process calling globus_gram_client_callback_allow().
  • attr — the set of client attributes used to contact the job. If you don't need custom attributes, pass the value GLOBUS_GRAM_CLIENT_NO_ATTR.
  • register_callback — a pointer to a function to call once the registration request has completed or failed.
  • register_callback_arg — a pointer to application-specific data that gets passed along to the function pointed to by register_callback as its user_callback_arg parameter.

Returns

Upon success, globus_gram_client_register_job_callback_unregistration() returns GLOBUS_SUCCESS, starts sending an unregister request to the job named by job_contact, and schedules the function pointed to by the register_callback parameter to be called ✨. If something goes sideways, it returns an integer error code telling you why it couldn't process the unregister request.

Return values

  • GLOBUS_GRAM_SUCCESS — Success
  • GLOBUS_GRAM_PROTOCOL_ERROR_MALLOC_FAILED — Out of memory
  • GLOBUS_GRAM_PROTOCOL_ERROR_PROTOCOL_FAILED — Protocol error
  • GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_JOB_CONTACT — Invalid job contact
  • GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST — Invalid request
  • GLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES — No resources

See also

globus_gram_client_job_callback_unregister()

🔥 globus_gram_client_register_job_cancel

int globus_gram_client_register_job_cancel (const char * job_contact,
    globus_gram_client_attr_t attr, globus_gram_client_nonblocking_func_t
    register_callback, void * register_callback_arg)

the "nvm bestie I'm done" call, iconic behavior honestly 💀. globus_gram_client_register_job_cancel() sends a message to a GRAM service to cancel a GRAM job.

Now here's the tea: depending on what state the job is in, the cancellation might be immediate or it might need a little delay while it interacts with the LRM servicing the job. Either way, this function returns as soon as it's able to start sending the message — it does not sit there waiting, she's booked and busy ✈️. Once the cancellation has been completely processed, notification that the job was successfully canceled gets sent to all client contacts registered for notifications. everybody gets the news, no gatekeeping 🎀.

Parameters

  • job_contact — a NULL-terminated character string containing a GRAM job contact that this function will contact to cancel the job.
  • attr — the set of client attributes used to contact the job. If you don't need custom attributes, pass the value GLOBUS_GRAM_CLIENT_NO_ATTR.
  • register_callback — a pointer to a function to call when the job_request request has completed or failed.
  • register_callback_arg — a pointer to application-specific data passed to the function pointed to by register_callback as its user_callback_arg parameter.

Returns

Upon succes, globus_gram_client_register_job_cancel() returns GLOBUS_SUCCESS if the cancellation was successful posted to the service ✅. If an error occurs, globus_gram_client_register_job_cancel() returns one an integer error code indicating why it could not cancel the job.

Return values

  • GLOBUS_GRAM_SUCCESS — Success
  • GLOBUS_GRAM_PROTOCOL_ERROR_MALLOC_FAILED — Out of memory
  • GLOBUS_GRAM_PROTOCOL_ERROR_PROTOCOL_FAILED — Protocol error
  • GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_JOB_CONTACT — Invalid job contact
  • GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST — Invalid request
  • GLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES — No resources

See also

globus_gram_client_job_cancel()

🦋 globus_gram_client_register_job_refresh_credentials

int globus_gram_client_register_job_refresh_credentials (char * job_contact,
    gss_cred_id_t creds, globus_gram_client_attr_t attr,
    globus_gram_client_nonblocking_func_t register_callback, void *
    register_callback_arg)

this one is giving "self-care for your credentials" 🌸. globus_gram_client_register_job_refresh_credentials() sends a "renew" signal to a GRAM service, and then kicks off delegating a brand new credential to the job manager and the job. It's literally here to stop the errors that happen when a credential expires. and it returns as soon as it's figured out its params are valid and started sending the message to the GRAM service — snappy, no cap ⚡.

Parameters

  • job_contact — the job contact string of the job to contact. Same value you got back from globus_gram_client_job_request().
  • creds — a GSSAPI credential handle that will be used to authenticate with the job manager and sign the delegated credential. You can set this parameter's value to GSS_C_NO_CREDENTIAL to say "yeah just use this process's default credential" 🙈.
  • attr — the set of client attributes used to contact the job. If you don't need custom attributes, pass the value GLOBUS_GRAM_CLIENT_NO_ATTR.
  • register_callback — a pointer to a function to call when the status request has completed or failed.
  • register_callback_arg — a pointer to application-specific data passed to the function pointed to by register_callback as its user_callback_arg parameter.

Returns

Upon success, the globus_gram_client_job_refresh_credentials() function returns GLOBUS_SUCCESS and begins sending the "renew" request to the GRAM service 💫. If an error occurs, globus_gram_client_job_refresh_credentials() returns an integer error code indicating why it can't refresh the job service's credential. Heads up bestie: the return code may be any value defined by the globus_gram_protocol_error_t enumeration, on top of the ones listed below 👇.

Return values

  • GLOBUS_GRAM_SUCCESS — Success
  • GLOBUS_GRAM_PROTOCOL_ERROR_MALLOC_FAILED — Out of memory
  • GLOBUS_GRAM_PROTOCOL_ERROR_PROTOCOL_FAILED — Protocol error
  • GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_JOB_CONTACT — Invalid job contact
  • GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST — Invalid request
  • GLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES — No resources

✨ globus_gram_client_register_job_request

int globus_gram_client_register_job_request (const char *
    resource_manager_contact, const char * description, int job_state_mask,
    const char * callback_contact, globus_gram_client_attr_t attr,
    globus_gram_client_nonblocking_func_t register_callback, void *
    register_callback_arg)

the big one, the main event, the moment 👑. globus_gram_client_register_job_request() sends a GRAM protocol message to a service asking it to start a job on behalf of the client. it's giving "hi bestie, could you run this for me" 💖.

Now listen: if globus_gram_client_register_job_request() figures out that this request could not be processed before contacting the gatekeeper (like, say, a malformed resource_manager_contact), it will return an error, and the regiser_callback function will not be called 🚫. Otherwise, the success or failure can be determined by the operation_failure_code parameter passed to the function pointed to by the register_callback parameter.

Parameters

  • resource_manager_contact — a NULL-terminated character string containing a GRAM contact that this function will contact.
  • description — a pointer to a string containing the job request information formatted in RSL syntax.
  • job_state_mask — a bitwise-or of the GLOBUS_GRAM_PROTOCOL_JOB_STATE_* states that the job manager will send job state notification messages for, to the contact named by callback_contact.
  • callback_contact — a GRAM listener contact that the job manager will send job state notification messages to.
  • attr — the set of client attributes used to contact the gatekeeper. If you don't need custom attributes, pass the value GLOBUS_GRAM_CLIENT_NO_ATTR.
  • register_callback — a pointer to a function to call when the job_request request has completed or failed.
  • register_callback_arg — a pointer to application-specific data passed to the function pointed to by register_callback as its user_callback_arg parameter.

Returns

Upon success, globus_gram_client_register_job_request() returns GLOBUS_SUCCESS and the register_callback function will be called once the job request operation completes 🌈. If an error occurs, this function returns an integer error code and the function pointed to by the register_callback parameter will not be called. rip to that callback 💀.

Return values

  • GLOBUS_SUCCESS — Success
  • GLOBUS_GRAM_PROTOCOL_ERROR_MALLOC_FAILED — Out of memory
  • GLOBUS_GRAM_PROTOCOL_ERROR_PROTOCOL_FAILED — Protocol error
  • GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_JOB_CONTACT — Invalid job contact
  • GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST — Invalid request
  • GLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES — No resources

🎀 globus_gram_client_register_job_request_with_info

int globus_gram_client_register_job_request_with_info (const char *
    resource_manager_contact, const char * description, int job_state_mask,
    const char * callback_contact, globus_gram_client_attr_t attr,
    globus_gram_client_info_callback_func_t callback, void * callback_arg)

same energy as the one above but she came with extensions 💅. globus_gram_client_register_job_request_with_info() sends a GRAM protocol message to a service asking it to start a job on behalf of the client — but with an extensions-aware callback. fancy. obsessed.

And just like before: if globus_gram_client_register_job_request_with_info() determines that this request could not be processed before contacting the gatekeeper (say it with me — a malformed resource_manager_contact 🙃), it will return an error, and the callback function will not be called. Otherwise, the success or failure can be determined by the operation_failure_code parameter passed to the function pointed to by the callback parameter.

And the difference between this function and globus_gram_client_register_job_request()? It's the function signature of the callback function. that's it, that's the plot twist ✨

Parameters 💖

  • resource_manager_contact — a NULL-terminated character string holding a GRAM contact that this function is gonna go contact. Like, actually reach out and touch. 👋
  • description — a pointer to a string with the job request info, formatted in RSL syntax. RSL or it didn't happen, bestie. ✨
  • job_state_mask — a bitwise-or of the GLOBUS_GRAM_PROTOCOL_JOB_STATE_* states that the job manager will send job state notification messages for, and it sends them to the contact named by callback_contact. Basically it's you telling the job manager which updates you're subscribed to. 🫶
  • callback_contact — a GRAM listener contact that the job manager will send those job state notification messages to. Your little mailbox. 📬
  • attr — a set of client attributes to use to contact the gatekeeper. If you don't need any custom attributes, pass the value GLOBUS_GRAM_CLIENT_NO_ATTR. Default is a vibe. 💅
  • callback — a pointer to a function to call when the job_request request has completed or failed.
  • callback_arg — a pointer to application-specific data, which will be passed to the function callback points to, as its user_callback_arg parameter. A lil snack you tuck into the callback's pocket. 🎀

Returns 🌸

Upon success, globus_gram_client_register_job_request_with_info() returns GLOBUS_SUCCESS and your callback function gets called once the job request operation completes. If an error occurs, this function returns an integer error code and the function pointed to by the callback parameter will not be called. No callback, no crumbs. 💀

Return values

  • GLOBUS_SUCCESS — Success
  • GLOBUS_GRAM_PROTOCOL_ERROR_MALLOC_FAILED — Out of memory
  • GLOBUS_GRAM_PROTOCOL_ERROR_PROTOCOL_FAILED — Protocol error
  • GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_JOB_CONTACT — Invalid job contact
  • GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST — Invalid request
  • GLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES — No resources

💅 globus_gram_client_register_job_signal

int globus_gram_client_register_job_signal (const char * job_contact,
    globus_gram_protocol_job_signal_t signal, const char * signal_arg,
    globus_gram_client_attr_t attr, globus_gram_client_nonblocking_func_t
    register_callback, void * register_callback_arg)

Send a signal a GRAM job. Okay so globus_gram_client_register_job_signal() fires off a signal message to a job that's managed by the GRAM service. A signal is a signal number plus an optional string argument — that's the whole shape of it. The meanings of the signals the GRAM job manager supports live in the GRAM Protocol documentation, so go read that if you're curious (iykyk). This function returns as soon as it's checked that its parameters are valid and it's started sending the message to the GRAM service. It does not wait around, she's booked and busy. 🔥

Parameters

  • job_contact — the job contact string of the job manager to contact. This is the same value that came back from globus_gram_client_job_request().
  • signal — the signal code to send to the job manager.
  • signal_arg — parameters for the signal, as described in the documentation for the #globus_gram_protocol_job_signal_t enumeration.
  • attr — a set of client attributes to use to contact the job. If no custom attributes are needed, the caller should pass the value GLOBUS_GRAM_CLIENT_NO_ATTR.
  • register_callback — a pointer to a function to call when the signal request has completed or failed.
  • register_callback_arg — a pointer to application-specific data, which will be passed to the function register_callback points to, as its user_callback_arg parameter.

Returns

Upon success, globus_gram_client_job_register_signal() returns GLOBUS_SUCCESS after beginning to send the signal to the GRAM job, and it registers the register_callback function to be called once that has completed. If an error occurs, this function returns an integer error code indicating why the client could not signal the job. 😭

Return values

  • GLOBUS_GRAM_SUCCESS — Success
  • GLOBUS_GRAM_PROTOCOL_ERROR_MALLOC_FAILED — Out of memory
  • GLOBUS_GRAM_PROTOCOL_ERROR_PROTOCOL_FAILED — Protocol error
  • GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_JOB_CONTACT — Invalid job contact
  • GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST — Invalid request
  • GLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES — No resources

See also

globus_gram_client_register_job_signal()

🦋 globus_gram_client_register_job_status

int globus_gram_client_register_job_status (const char * job_contact,
    globus_gram_client_attr_t attr, globus_gram_client_nonblocking_func_t
    register_callback, void * register_callback_arg)

Send a status query to a GRAM job. globus_gram_client_register_job_status() kicks off a query of the current status of the job tied to the job_contact parameter. The job's status and failure code get handed over to the function register_callback points to. And this one returns as soon as it's begun requesting the job status — no waiting, no drama. 🌈

Parameters

  • job_contact — the job contact string of the job to query. This is the same value returned from globus_gram_client_job_request().
  • attr — a set of client attributes to use to contact the job. If no custom attributes are needed, the caller should pass the value GLOBUS_GRAM_CLIENT_NO_ATTR.
  • register_callback — a pointer to a function to call when the status request has completed or failed.
  • register_callback_arg — a pointer to application-specific data, which will be passed to the function register_callback points to, as its user_callback_arg parameter.

Returns

Upon success, the globus_gram_client_register_job_status() function returns GLOBUS_SUCCESS, starts sending a job state query to the job named by job_contact, and registers the function register_callback points to so it gets called once the status query terminates or fails. If an error occurs, globus_gram_client_register_job_status() returns an integer error code. Simple as that. 💖

Return values

  • GLOBUS_GRAM_SUCCESS — Success
  • GLOBUS_GRAM_PROTOCOL_ERROR_MALLOC_FAILED — Out of memory
  • GLOBUS_GRAM_PROTOCOL_ERROR_PROTOCOL_FAILED — Protocol error
  • GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_JOB_CONTACT — Invalid job contact
  • GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST — Invalid request
  • GLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES — No resources
  • GLOBUS_GRAM_PROTOCOL_ERROR_NULL_PARAMETER — Null parameter

🧚 globus_gram_client_register_job_status_with_info

int globus_gram_client_register_job_status_with_info (const char *
    job_contact, globus_gram_client_attr_t attr,
    globus_gram_client_info_callback_func_t info_callback, void *
    callback_arg)

Send a status query to a GRAM job, but make it informative. globus_gram_client_register_job_status_with_info() initiates a query of the current status of the job associated with the job_contact parameter. The job information comes back through the job_info parameter passed to the function info_callback points to. And yes, this function also returns as soon as it has begun requesting the job status. Fast girl behavior. ⭐

Parameters

  • job_contact — the job contact string of the job to query. This is the same value returned from globus_gram_client_job_request().
  • attr — a set of client attributes to use to contact the job. If no custom attributes are needed, the caller should pass the value GLOBUS_GRAM_CLIENT_NO_ATTR.
  • info_callback — a pointer to a function to call when the status request has completed or failed.
  • callback_arg — a pointer to application-specific data, which will be passed to the function info_callback points to, as its user_callback_arg parameter.

Returns

Upon success, the globus_gram_client_register_job_status_with_info() function returns GLOBUS_SUCCESS, starts sending a job state query to the job named by job_contact, and registers the function info_callback points to so it's called once the status query terminates or fails. If an error occurs, globus_gram_client_register_job_status_with_info() returns an integer error code. 👑

Return values

  • GLOBUS_GRAM_SUCCESS — Success
  • GLOBUS_GRAM_PROTOCOL_ERROR_MALLOC_FAILED — Out of memory
  • GLOBUS_GRAM_PROTOCOL_ERROR_PROTOCOL_FAILED — Protocol error
  • GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_JOB_CONTACT — Invalid job contact
  • GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST — Invalid request
  • GLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES — No resources
  • GLOBUS_GRAM_PROTOCOL_ERROR_NULL_PARAMETER — Null parameter

🎀 globus_gram_client_register_ping

int globus_gram_client_register_ping (const char * resource_manager_contact,
    globus_gram_client_attr_t attr, globus_gram_client_nonblocking_func_t
    register_callback, void * register_callback_arg)

Send a ping request to a GRAM service. globus_gram_client_register_ping() sends a specially-formatted GRAM protocol message that checks whether a Gatekeeper is even running on a given PORT, and whether that Gatekeeper is configured to support the job manager service you want. This one is purely for diagnostic purposes — it's the "hey bestie, you up?" of the GRAM protocol. 🙈

If globus_gram_client_register_ping() figures out that this request could not be processed before contacting the gatekeeper (say, a malformed resource_manager_contact), it will return an error and the regiser_callback function will not be called. Otherwise, the success or failure can be determined by the operation_failure_code parameter to the function register_callback points to. ✨

Parameters

  • resource_manager_contact — a NULL-terminated character string containing a GRAM contact that this function will contact.
  • attr — a set of client attributes to use to contact the gatekeeper. If no custom attributes are needed, the caller should pass the value GLOBUS_GRAM_CLIENT_NO_ATTR.
  • register_callback — a pointer to a function to call when the ping request has completed or failed.
  • register_callback_arg — a pointer to application-specific data, which will be passed to the function register_callback points to, as its user_callback_arg parameter.

Returns

Upon success, globus_gram_client_register_ping() returns GLOBUS_SUCCESS and the register_callback function will be called once the ping operation completes. If an error occurs, this function returns an integer error code and the function pointed to by the register_callback parameter will not be called. 🫶

Return values

  • GLOBUS_SUCCESS — Success
  • GLOBUS_GRAM_PROTOCOL_ERROR_MALLOC_FAILED — Out of memory
  • GLOBUS_GRAM_PROTOCOL_ERROR_PROTOCOL_FAILED — Protocol error
  • GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_JOB_CONTACT — Invalid job contact
  • GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST — Invalid request
  • GLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES — No resources

✨ Author ✨

Generated automatically by Doxygen for globus_gram_client from the source code.

And that's the whole page, bestie — you made it to the end, main character energy fr fr. 💜 This one is globus_gram_client, Version 14.7, straight outta the globus_gram_client source code, and the footer's globus_gra..._functions(3) is just the manpage name doing its little truncated thing. Go forth and signal some jobs. 💅🌸

📦 where this page comes from