GRAM Job Functions

Functions


Function Documentation

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 
)

Verify that a gatekeeper is running (nonblocking).

Sends a specially-formated GRAM protocol message which checks to see if a Globus Gatekeeper is running on a given PORT, and whether that Gatekeeper is configured to support the desired job manager service. This is primarily used for diagnostic purposes.

If this function determines that the ping could not be processed before contacting the gatekeeper (for example, a malformed resource_manager_contact), it will return an error, and the regiser_callback function will not be called.

Parameters:
resource_manager_contact A NULL-terminated character string containing a GRAM contact.
attr Client attributes to be used. Should be set to GLOBUS_GRAM_CLIENT_NO_ATTR if no attributes are to be used.
register_callback The callback function to call when the ping request has completed.
register_callback_arg A pointer to user data which will be passed to the callback as it's user_callback_arg.
Returns:
This function returns GLOBUS_SUCCESS if The gatekeeper contact is valid, the client was able to authenticate with the Gatekeeper, and the Gatekeeper was able to locate the requested service. Otherwise one of the GLOBUS_GRAM_PROTOCOL_ERROR values is returned.
int globus_gram_client_ping ( const char *  resource_manager_contact  ) 

Verify that a gatekeeper is running.

Sends a specially-formated GRAM protocol message which checks to see if a Globus Gatekeeper is running on a given PORT, and whether that Gatekeeper is configured to support the desired job manager service. This is primarily used for diagnostic purposes.

This function blocks while processing the ping request.

Parameters:
resource_manager_contact A NULL-terminated character string containing a GRAM contact.
Returns:
This function returns GLOBUS_SUCCESS if The gatekeeper contact is valid, the client was able to authenticate with the Gatekeeper, and the Gatekeeper was able to locate the requested service. Otherwise one of the GLOBUS_GRAM_PROTOCOL_ERROR values is returned.
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 
)

Request a job be started (nonblocking).

Request access to interactive resources at the current time. A job request is atomic: either all of the requested processes are created, or none are created. This is the nonblocking version of globus_gram_client_job_request(). Instead of waiting for the job manager to acknowledge that the job has been submitted or started, this function immediately returns after beginning the job submission. The register_callback function will be called to let the caller know whether the job request has been submitted successfully or not.

If this function determines that the job request could not be processed before contacting the job manager (for example, a malformed resource_manager_contact) it will return an error, and the register_callback function will not be called.

Parameters:
resource_manager_contact A NULL-terminated character string containing a GRAM contact.
description An RSL description of the requested job. A GRAM RSL consists of a conjunction of RSL parameters .
job_state_mask 0, a bitwise OR of the GLOBUS_GRAM_PROTOCOL_JOB_STATE_* states, or GLOBUS_GRAM_PROTOCOL_JOB_STATE_ALL.
callback_contact The URL which will receive all messages about the job.
attr Client attributes to be used. Should be set to GLOBUS_GRAM_CLIENT_NO_ATTR if no attributes are to be used.
register_callback The callback function to call when the job request submission has completed. This function will be passed a copy of the job_contact which the user must free, and an error code (the job status value is undefined).
register_callback_arg A pointer to user data which will be passed to the callback as it's user_callback_arg.
Returns:
This function returns GLOBUS_SUCCESS if successful, otherwise one of the GLOBUS_GRAM_PROTOCOL_ERROR values is returned.
See also:
Resource Manager Contact
globus_gram_client_job_request()
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 
)

Request a job be started.

Request access to interactive resources at the current time. A job request is atomic: either all of the requested processes are created, or none are created.

Parameters:
resource_manager_contact A NULL-terminated character string containing a GRAM contact.
description An RSL description of the requested job. A GRAM RSL consists of a conjunction of RSL parameters .
job_state_mask 0, a bitwise OR of the GLOBUS_GRAM_PROTOCOL_JOB_STATE_* states, or GLOBUS_GRAM_PROTOCOL_JOB_STATE_ALL.
callback_contact The URL which will receive all messages about the job.
job_contact In a successful case, this is set to a unique identifier for each job.
Returns:
This function returns GLOBUS_SUCCESS if successful, otherwise one of the GLOBUS_GRAM_PROTOCOL_ERROR values is returned.
See also:
Resource Manager Contact
int globus_gram_client_job_cancel ( const char *  job_contact  ) 

Cancel a GRAM-managed job.

Removes a PENDING job request, or kills all processes associated with an ACTIVE job, releasing any associated resources

Parameters:
job_contact The job contact string of the job to contact. This is the same value returned from globus_gram_client_job_request() or globus_gram_client_register_job_request().
Returns:
This function returns GLOBUS_SUCCESS if the cancellation was successful. Otherwise one of the GLOBUS_GRAM_PROTOCOL_ERROR_* values will be returned, indicating why the client could not cancel the job.
See also:
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 
)

Nonblocking cancel of a GRAM-managed job.

Removes a PENDING job request, or kills all processes associated with an ACTIVE job, releasing any associated resources

Parameters:
job_contact The job contact string of the job to contact. This is the same value returned from globus_gram_client_job_request() or globus_gram_client_register_job_request().
attr Client attributes to be used. Should be set to GLOBUS_GRAM_CLIENT_NO_ATTR if no attributes are to be used.
register_callback The callback function to call when the job request cancel has completed.
register_callback_arg A pointer to user data which will be passed to the callback as it's user_callback_arg.
Returns:
This function returns GLOBUS_SUCCESS if successful, otherwise one of the GLOBUS_GRAM_PROTOCOL_ERROR values is returned.
See also:
globus_gram_client_job_cancel()
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 
)

Signal a job manager.

Send a signal to a GRAM job manager to modify the way it handles a job request. Signals consist of a signal number, and an optional string argument. The meanings of the signals supported by the GRAM job manager are defined in the GRAM Protocol documentation

Parameters:
job_contact The job contact string of the job manager to signal.
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.
job_status A pointer to an integer which will return the new job status, if the signal causes the job's state to change (for example, the GLOBUS_GRAM_PROTOCOL_JOB_CANCEL signal will cause the job to enter the GLOBUS_GRAM_PROTOCOL_JOB_STATE_FAILED).
failure_code An error code indicating why the job manager could not process the signal.
Returns:
This function returns GLOBUS_SUCCESS if the signal was successful. Otherwise one of the GLOBUS_GRAM_PROTOCOL_ERROR_* values will be returned, indicating why the client could not signal the job.
See also:
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 
)

Nonblocking signal a job manager.

Send a signal to a GRAM job manager to modify the way it handles a job request. Signals consist of a signal number, and an optional string argument. The meanings of the signals supported by the GRAM job manager are defined in the GRAM Protocol documentation

Parameters:
job_contact The job contact string of the job manager to signal.
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.
attr Client attributes to be used. Should be set to GLOBUS_GRAM_CLIENT_NO_ATTR if no attributes are to be used.
register_callback The callback function to call when the job signal has completed.
register_callback_arg A pointer to user data which will be passed to the callback as it's user_callback_arg.
Returns:
This function returns GLOBUS_SUCCESS if successful, otherwise one of the GLOBUS_GRAM_PROTOCOL_ERROR values is returned.
int globus_gram_client_job_status ( const char *  job_contact,
int *  job_status,
int *  failure_code 
)

Query a job's status.

This function queries the status of the job associated with the job contact, returning it's current job status and job failure reason if it has failed.

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 A pointer to an integer which will be populated with the current status of the job. This will be one of the GLOBUS_GRAM_PROTOCOL_JOB_STATE_* values if this function is successful.
failure_code The reason why the job failed if the job_status is set to GLOBUS_GRAM_PROTOCOL_JOB_STATE_FAILED.
Returns:
This function returns GLOBUS_SUCCESS if the job state query was successfully. Otherwise one of the GLOBUS_GRAM_PROTOCOL_ERROR_* values will be returned, indicating why the client could not query the job state.
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 
)

Nonblocking query of a job's status.

This function queries the status of the job associated with the job contact, returning it's current job status and job failure reason if it has failed.

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 Client attributes to be used. Should be set to GLOBUS_GRAM_CLIENT_NO_ATTR if no attributes are to be used.
register_callback Callback function to be called when the job status query has been processed.
register_callback_arg A pointer to user data which will be passed to the callback as it's user_callback_arg.
Returns:
This function returns GLOBUS_SUCCESS if the job state query was successfully. Otherwise one of the GLOBUS_GRAM_PROTOCOL_ERROR_* values will be returned, indicating why the client could not query the job state.
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 
)

Register a callback contact for job state changes.

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 mask indicating which job state changes should be sent to the callback_contact. This may be 0 (no job state changes), a bitwise-or of the GLOBUS_GRAM_PROTOCOL_JOB_STATE_* states, or GLOBUS_GRAM_PROTOCOL_JOB_STATE_ALL to register for all job states.
callback_contact A URL string containing a GRAM client callback. This string should normally be generated by a process calling globus_gram_client_callback_allow().
job_status A pointer to an integer which will be populated with the current status of the job. This will be one of the GLOBUS_GRAM_PROTOCOL_JOB_STATE_* values if this function is successful.
failure_code Set to an error code when the job manager is unable to process this registration.
Returns:
This function returns GLOBUS_SUCCESS if the callback registration was successful. Otherwise one of the GLOBUS_GRAM_PROTOCOL_ERROR_* values will be returned, indicating why the client could not register the callback contact.
int globus_gram_client_job_callback_unregister ( const char *  job_contact,
const char *  callback_contact,
int *  job_status,
int *  failure_code 
)

Unregister a callback contact from future job state changes.

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().
callback_contact A URL string containing a GRAM client callback. This string should normally be generated by a process calling globus_gram_client_callback_allow(). If this function returns successfully, the process managing the callback_contact should not receive future job state changes.
job_status A pointer to an integer which will be populated with the current status of the job. This will be one of the GLOBUS_GRAM_PROTOCOL_JOB_STATE_* values if this function is successful.
failure_code Set to an error code when the job manager is unable to process this registration.
Returns:
This function returns GLOBUS_SUCCESS if the callback unregistration was successful. Otherwise one of the GLOBUS_GRAM_PROTOCOL_ERROR_* values will be returned, indicating why the client could not unregister the callback contact.
int globus_gram_client_job_refresh_credentials ( char *  job_contact,
gss_cred_id_t  creds 
)

Delegate new credentials to a job manager.

This function performs a new delegation handshake with the job manager, updating it with a new user proxy. This will allow the job manager to continue to send job state callbacks after the original proxy would have expired.

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().
creds A credential which should be used to contact the job manager. This may be GSS_C_NO_CREDENTIAL to use the process's default credential.
Returns:
This function returns GLOBUS_SUCCESS if the delegation was successful. Otherwise one of the GLOBUS_GRAM_PROTOCOL_ERROR_* values will be returned, indicating why the client could not unregister the callback contact.
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 
)

Delegate new credentials to a job manager (nonblocking).

This function performs the same operation as globus_gram_client_job_refresh_credentials(), but without blocking the calling thread. Once the delegation has completed, it's final status will be reported in the register_callback.

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().
creds A credential which should be used to contact the job manager. This may be GSS_C_NO_CREDENTIAL to use the process's default credential.
attr Client attributes to be used. Should be set to GLOBUS_GRAM_CLIENT_NO_ATTR if no attributes are to be used.
register_callback Callback function to be called when the job refresh has been processed.
register_callback_arg A pointer to user data which will be passed to the callback as it's user_callback_arg.
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 
)

Nonblocking register a callback contact for job state changes.

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 mask indicating which job state changes should be sent to the callback_contact. This may be 0 (no job state changes), a bitwise-or of the GLOBUS_GRAM_PROTOCOL_JOB_STATE_* states, or GLOBUS_GRAM_PROTOCOL_JOB_STATE_ALL to register for all job states.
callback_contact A URL string containing a GRAM client callback. This string should normally be generated by a process calling globus_gram_client_callback_allow().
attr Client attributes to be used. Should be set to GLOBUS_GRAM_CLIENT_NO_ATTR if no attributes are to be used.
register_callback The callback function to call when the job signal has completed.
register_callback_arg A pointer to user data which will be passed to the callback as it's user_callback_arg.
Returns:
This function returns GLOBUS_SUCCESS if the successfull, otherwise one of the GLOBUS_GRAM_PROTOCOL_ERROR_* values will be returned, indicating why the operation failed.
See also:
globus_gram_client_job_callback_register()
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 
)

Nonblocking unregistration of a callback contact.

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().
callback_contact A URL string containing a GRAM client callback. This string should normally be generated by a process calling globus_gram_client_callback_allow(). If this function returns successfully, the process managing the callback_contact should not receive future job state changes.
attr Client attributes to be used. Should be set to GLOBUS_GRAM_CLIENT_NO_ATTR if no attributes are to be used.
register_callback The callback function to call when the job signal has completed.
register_callback_arg A pointer to user data which will be passed to the callback as it's user_callback_arg.
Returns:
This function returns GLOBUS_SUCCESS if the successfull, otherwise one of the GLOBUS_GRAM_PROTOCOL_ERROR_* values will be returned, indicating why the operation failed.
See also:
globus_gram_client_job_callback_unregister()

about globus | globus toolkit | dev.globus

Comments? webmaster@globus.org