Goals
Implementation of DRMAAv2 Specification
Background and strategic fit
The Distributed Resource Management Application API Version 2 (DRMAA) specification defines an interface for tightly coupled, but still portable access to the majority of DRM systems. PBS is Distributed Resource Management system(DRMS). Standardized access to PBS product through a DRMAAv2 implementation(API). High-level API designers, meta-scheduler architects and end users can rely on DRMAAv2 implementations for a unified access to execution resources.
DRMAAv2 Specification (Distributed Resource Management Application API 2)
Overview
As we all know open standards are taking major role in the exponential growth in many areas. DRMAA2 is such an open standard. It is the successor of the wide-spread DRMAA. DRMAA is generally used for submitting jobs (or creating job work-flows) into a compute cluster by using a cluster resource management system like PBS Professional. Unlike DRMAA with DRMAA2 you can not only submit jobs, you can also get cluster related information, like getting host names, types and status information or insight about queues configured in the resource management system. You can also monitor jobs not submitted within the application. Overall it covers many more use cases than the old DRMAA standard.
More details of DRMAA2 specification can be found from the following document.
https://www.ogf.org/documents/GFD.231.pdf
Assumptions
Requirements
The implementation of DRMAA2 specification for PBS Pro is broadly divided into the following requirements/user stories.
| # | User Story | Importance | Notes |
|---|
| 1 |
PP-628
-
Getting issue details...
STATUS
| |
|
| 2 |
PP-634
-
Getting issue details...
STATUS
|
|
|
| 3 |
PP-631
-
Getting issue details...
STATUS
|
|
|
| 4 |
PP-630
-
Getting issue details...
STATUS
|
|
|
| 5 |
PP-629
-
Getting issue details...
STATUS
|
|
|
| 6 |
PP-632
-
Getting issue details...
STATUS
|
|
|
| 7 |
PP-633
-
Getting issue details...
STATUS
|
|
|
| 8 |
PP-643
-
Getting issue details...
STATUS
|
|
|
| 9 |
PP-626
-
Getting issue details...
STATUS
|
|
|
| 10 |
PP-644
-
Getting issue details...
STATUS
|
|
|
| 11 |
PP-636
-
Getting issue details...
STATUS
|
|
|
Architecture and design
Application stack
.png?version=1&modificationDate=1485189110317&cacheVersion=1&api=v2&effects=border-simple%2Cblur-border&width=713&height=413)
DRMAA2 Layout
Error rendering macro 'viewpdf' : Failed to find attachment with Name DRMAAv2_Layout.pdf
Domain model diagram
.png?version=1&modificationDate=1485180716842&cacheVersion=1&api=v2&effects=border-simple%2Cblur-border&width=1153&height=733)
ConnectionPool is set active connection with PBSPro. In multi-threaded application each thread uses one connection. ConnectionPool Is Member of DRMSystem
Overview of Object mapping
Error rendering macro 'viewpdf' : Failed to find attachment with Name DRMAA2Overview.pdf
DRMAA2 spec relies on concept of session to support the persistency of job and reservation information in multiple runs of short lived applications.
The SessionManager interface is the main interface of a DRMAA implementation for establishing communication with the DRMS. By the help of this interface, sessions for job management, monitoring, and/or reservation management can be maintained.
- JobSession allows us to submit, control and monitor jobs. As opposed to MonitoringSession this allows us to control and monitor only those jobs submitted with in this job session only.
- MonitoringSession allows us to get on-line status of jobs submitted with in DRMAA2 JobSession/s as well as those submitted outside of DRMAA2 as well. Within a monitoring session we can't submit or control jobs. Due to this reason we can say that DRMAA2 is good to write Job Monitoring GUIs.
- ReservationSession allows us to submit, control and monitor standing or advanced reservations.
Refer DRMAAv2 document for description of Objects
Few important Sequence diagram
Source Directory structure in github
├── ...
├── pbspro
│ ├── src
│ ├── ├── lib
│ ├── ├── ├── Libdrmaa2 DRMAAv2 module Top level directory
│ ├── ├── ├── ├── libdrmaa2 All the function prototypes and definitions included in this API. Autoconf and libtool specification to create library.
│ ├── ├── ├── ├── ├── -- drmaa2.cpp API definitions
│ ├── ├── ├── ├── ├── -- drmaa2.h API and declaration
│ ├── ├── ├── ├── src Core infrastructure source files
│ ├── ├── ├── ├── inc Core infrastructure internal include files
│ ├── ├── ├── ├── White-box testing
│ ├── ├── ├── ├── ├── src Source for unit-testing
│ ├── ├── ├── ├── ├── inc Internal include files for unit-testing
│ ├──
│ ├──
│ -- Doxygen.in Doxygen configure file
│ --
Directory structure in target
├── ...
├── $(PBS_EXEC)
│ ├── lib
│ ├── ├── libdrmaav2.so
│ ├── include
│ ├── ├── drmaav2.h
Dependent packages
PBSPro - libdrmaav2.so needs libpbs.so library for IFL calls
cppunit - for unittesting
doxygen - for generating docs
Compiling DRMAA2 applications for PBS Pro
It is assumed that libdrmaa2.so or libdrmaa2.a is installed as follows prior to compiling a DRMAA2 application.
rpm --install <rpm for libdrmaav2 for PBS Pro>
Example: rpm --install libdrmaav2_pbspro-1.0-17.x86_64.rpm
By default this will install the library to /usr/lib/libdrmaa2.*(so or a) and the headers are installed at /usr/include/drmaa2.
Now DRMAA2 application can be compiled as follows.
gcc -I/usr/include/drmaa2 -L/usr/lib/libdrmaa2.so <drmaa2_app> -ldrmaa2
We also need to set the following before starting the application if in case we are using shared library.
export LD_LIBRARY_PATH=/usr/lib/libdrmaa2.so ./<drmaa2_app>
APIs defined in DRMAAv2 specification
drmaa2_error drmaa2_close_jsession (drmaa2_jsession js_)
drmaa2_close_jsession - closes the drmaa2_job session pointed by js
Parameters:
js_ - pointer to drmaa2_job session which needs to be closed
Side-Effects: none
Returns:
drmaa2_error - returns DRMAA2_SUCCESS if successful returns DRMAA2_INVALID_SESSION if session is invalid
drmaa2_error drmaa2_close_msession (drmaa2_msession ms_)
Dis-associates monitoring session from DRMS. Should be callable only once else it should return DRMAA2_INVALID_SESSION error.
Parameters:
ms_ - pointer to drmaa2 monitoring session created earlier.
Side-Effects: none
Returns:
NULL and also sets sets drmaa2_lasterror_v to DRMAA2_INVALID_SESSION error if fails DRMAA2_SUCCESS if succeeds
drmaa2_error drmaa2_close_rsession (drmaa2_rsession rs_)
Disassociates reservation session from DRMS. Should be callable only once else it should return DRMAA2_INVALID_SESSION error.
Parameters:
rs_ - pointer to drmaa2 reservation session created earlier.
Side-Effects: none
Returns:
NULL and also sets sets drmaa2_lasterror_v to DRMAA2_INVALID_SESSION error if fails DRMAA2_SUCCESS if succeeds
drmaa2_jsession drmaa2_create_jsession (const char * session_name_, const char * contact_)
Creates a drmaa2 job session for a given name and contact.
Parameters:
session_name_ - Name of the session .
contact_ - DRMS name.
Side-Effects: none
Returns:
drmaa2_jsession if succeeds NULL if fails and sets drmaa2_lasterror_v to DRMAA2_INVALID_ARGUMENT error.
drmaa2_rsession drmaa2_create_rsession (const char * session_name_, const char * contact_)
Creates a drmaa2 reservation session for a given name and contact.
Parameters:
session_name_ - Name of the session.
contact_ - DRMS name.
Side-Effects: none
Returns:
drmaa2_jsession if succeeds NULL if fails and sets drmaa2_lasterror_v to DRMAA2_INVALID_ARGUMENT error.
drmaa2_string drmaa2_describe_attribute (const void * instance, const char * name)
drmaa2_error drmaa2_destroy_jsession (const char * session_name_)
drmaa2_destroy_jsession - destroys the drmaa2_job session pointed by js
Parameters:
session_name_ - pointer to drmaa2_job session which needs to be closed
Side-Effects: none
Returns:
drmaa2_error - returns DRMAA2_SUCCESS if successful returns DRMAA2_INVALID_ARGUMENT if session name is invalid
drmaa2_error drmaa2_destroy_rsession (const char * session_name_)
Reaps the persisted or cached state information for the given session name.
Parameters:
session_name_ - Name of the session.
Side-Effects: none
Returns:
NULL and also sets sets drmaa2_lasterror_v to DRMAA2_INVALID_SESSION error if fails DRMAA2_SUCCESS if succeeds
drmaa2_dict drmaa2_dict_create (const drmaa2_dict_entryfree callback)
This function creates a drmaa dictionary.
Parameters:
callback - Call back function to call when free is called.
Side-Effects: none
Returns:
drmaa2_dict
drmaa2_error drmaa2_dict_del (drmaa2_dict d, const char * key)
This function deletes the entry with specified key from the dictionary.
Parameters:
d - Pointer to drmaa dict
key - pointer to key string
Side-Effects: none
Returns:
drmaa2_error
Return values:
DRMAA2_INVALID_ARGUMENT
void drmaa2_dict_free (drmaa2_dict * dRef)
This function frees a drmaa dict.
Parameters:
dRef - Pointer to drmaa dict
Side-Effects: none
Returns:
void
const char* drmaa2_dict_get (const drmaa2_dict d, const char * key)
This function gets the key's value from the dictionary.
Parameters:
d - Pointer to drmaa dict
key - pointer to key string
Side-Effects: none
Returns:
char *
drmaa2_bool drmaa2_dict_has (const drmaa2_dict d, const char * key)
This function checks for the presence of key in the dictionary.
Parameters:
d - Pointer to drmaa dict
key - pointer to key string
Side-Effects: none
Returns:
drmaa2_bool
drmaa2_string_list drmaa2_dict_list (const drmaa2_dict d)
This function returns a drmaa list of keys in the dictionary.
Parameters:
d - Pointer to drmaa dict
Side-Effects: none
Returns:
drmaa2_string_list
drmaa2_error drmaa2_dict_set (drmaa2_dict d, const char * key, const char * val)
This function sets the key value pair to the dictionary.
Parameters:
d - Pointer to drmaa dict
key - pointer to key string
val - pointer to value string
Side-Effects: none
Returns:
drmaa2_error
Return values:
DRMAA2_INVALID_ARGUMENT DRMAA2_SUCCESS
drmaa2_string drmaa2_get_drmaa_name (void)
drmaa2_get_drmaa_name - returns the DRM application name
Parameters:
- void
Side-Effects: none
Returns:
drmaa2_string
drmaa2_version drmaa2_get_drmaa_version (void)
drmaa2_get_drmaa_version - returns the DRM application version
Parameters:
- void
Side-Effects: none
Returns:
drmaa2_version
drmaa2_string drmaa2_get_drms_name (void)
drmaa2_get_drms_name - returns the DRM system name
Parameters:
- void
Side-Effects: none
Returns:
drmaa2_string
drmaa2_version drmaa2_get_drms_version (void)
drmaa2_get_drms_version - returns the DRM system version
Parameters:
- void
Side-Effects: none
Returns:
drmaa2_version
drmaa2_string drmaa2_get_instance_value (const void * instance, const char * name)
drmaa2_string_list drmaa2_get_jsession_names (void)
drmaa2_get_jsession_names - returns the list of drmaa2_job sessions
Side-Effects: none
Returns:
drmaa2_string_list - returns list of job session names available
drmaa2_string_list drmaa2_get_rsession_names (void)
Get a list of all reservation session names.
Side-Effects: none
Returns:
drmaa2_string_list
Return values:
NULL - If there are no existing reservation sessions
· If this feature is not supported, set drmaa2_lasterror_v to DRMAA2_UNSUPPORTED_OPERATION
void drmaa2_j_free (drmaa2_j * j)
drmaa2_j_free - frees the drmaa2_job structure pointed by j
Parameters:
j - pointer to drmaa2_job
Side-Effects: none
Returns:
void
drmaa2_string drmaa2_j_get_id (const drmaa2_j j)
drmaa2_j_get_id() - Returns newly allocated drmaa2_job id string
Parameters:
j - pointer to drmaa2_job structure.
Side-Effects: none
Returns:
drmaa2_string - Gets the job id from drmaa2_job
drmaa2_jinfo drmaa2_j_get_info (const drmaa2_j j)
drmaa2_j_get_info() - Gets drmaa2_job info structure from the drmaa2_job in drmaa2_j structure.
Parameters:
j - pointer to drmaa2_job structure.
Side-Effects: none
Returns:
drmaa2_jinfo - returns drmaa2_jinfo if successful
drmaa2_jtemplate drmaa2_j_get_jt (const drmaa2_j j)
drmaa2_j_get_jt() - Returns pointer of drmaa2_job template structure from Job.
Parameters:
j - pointer to drmaa2_job structure.
Side-Effects: none
Returns:
drmaa2_string - Gets the job template from drmaa2_job
drmaa2_string drmaa2_j_get_session_name (const drmaa2_j j)
drmaa2_j_get_session_name() - Returns newly allocated session name string
Parameters:
j - pointer to drmaa2_job structure.
Side-Effects: none
Returns:
drmaa2_string - gets the session name from drmaa2_session
drmaa2_jstate drmaa2_j_get_state (const drmaa2_j j, drmaa2_string * substate)
drmaa2_j_get_state() - Gets drmaa2_job state from the drmaa2_job in drmaa2_j structure.
Parameters:
j - pointer to drmaa2_job structure.
substate - state of the drmaa2_job in drmaa2_j structure
Side-Effects: none
Returns:
drmaa2_jstate - returns current drmaa2_job state
drmaa2_error drmaa2_j_hold (drmaa2_j j)
drmaa2_j_hold() - Holds the drmaa2_job in drmaa2_j structure.
Parameters:
j - pointer to drmaa2_job structure.
Side-Effects: none
Returns:
drmaa2_error - Returns DRMAA2_SUCCESS on success Returns DRMAA2_INVALID_STATE if job state is invalid for hold
drmaa2_error drmaa2_j_release (drmaa2_j j)
drmaa2_j_release() - Releases the drmaa2_job in drmaa2_j structure.
Parameters:
j - pointer to drmaa2_job structure.
Side-Effects: none
Returns:
drmaa2_error - Returns DRMAA2_SUCCESS on success Returns DRMAA2_INVALID_STATE if job state is invalid for release
drmaa2_error drmaa2_j_resume (drmaa2_j j)
drmaa2_j_resume() - Resumes the drmaa2_job in drmaa2_j structure.
Parameters:
j - pointer to drmaa2_job structure.
Side-Effects: none
Returns:
drmaa2_error - Returns DRMAA2_SUCCESS on success Returns DRMAA2_INVALID_STATE if job state is invalid for resume
drmaa2_error drmaa2_j_suspend (drmaa2_j j)
drmaa2_j_suspend() - Suspends the drmaa2_job in drmaa2_j structure.
Parameters:
j - pointer to drmaa2_job structure.
Side-Effects: none
Returns:
drmaa2_error - Returns DRMAA2_SUCCESS on success Returns DRMAA2_INVALID_STATE if job state is invalid for suspend
drmaa2_error drmaa2_j_terminate (drmaa2_j j)
drmaa2_j_terminate() - Terminates the drmaa2_job in drmaa2_j structure.
Parameters:
j - pointer to drmaa2_job structure.
Side-Effects: none
Returns:
drmaa2_error - Returns DRMAA2_SUCCESS on success
drmaa2_error drmaa2_j_wait_started (const drmaa2_j j, const time_t timeout)
drmaa2_j_wait_started() - Blocks till the drmaa2_job is started or till timeout expires
Parameters:
j - pointer to drmaa2_job structure.
timeout - Timeout in time_t format.
Side-Effects: none
Returns:
drmaa2_error - returns DRMAA2_SUCCESS if successful returns DRMAA2_TIMEOUT if timeout happened
drmaa2_error drmaa2_j_wait_terminated (const drmaa2_j j, const time_t timeout)
drmaa2_j_wait_terminated() - Blocks till the drmaa2_job is terminated or till timeout expires
Parameters:
j - pointer to drmaa2_job structure.
timeout - Timeout in time_t format.
Side-Effects: none
Returns:
drmaa2_error - returns DRMAA2_SUCCESS if successful returns DRMAA2_TIMEOUT if timeout happened
void drmaa2_jarray_free (drmaa2_jarray * ja)
drmaa2_jarray_free - frees the drmaa2_job array structure pointed by ja
Parameters:
ja - pointer to DRMAA jo array
Side-Effects: none
Returns:
void
drmaa2_string drmaa2_jarray_get_id (const drmaa2_jarray ja)
drmaa2_jarray_get_id() Gets the id from drmaa2 drmaa2_job array.
Parameters:
ja - pointer to drmaa2_job array
Side-Effects: none
Returns:
drmaa2_string - job id of drmaa2_job array
drmaa2_jtemplate drmaa2_jarray_get_job_template (const drmaa2_jarray ja)
drmaa2_jarray_get_job_template - returns the drmaa2_job template used to submit the drmaa2_job array.
Parameters:
ja - pointer to drmaa2_job array
Side-Effects: none
Returns:
drmaa2_jtemplate - returns job template from drmaa2_job array
drmaa2_j_list drmaa2_jarray_get_jobs (const drmaa2_jarray ja)
drmaa2_jarray_get_jobs() Returns the list of jobs in the drmaa2_job array structure.
Parameters:
ja - Pointer to drmaa2_job array structure
Side-Effects: none
Returns:
drmaa2_j_list - gets list of drmaa2_jobs from drmaa2_jarray
drmaa2_string drmaa2_jarray_get_session_name (const drmaa2_jarray ja)
drmaa2_jarray_get_session_name - gets the session name in which the drmaa2_job array is submitted
Parameters:
ja - pointer to drmaa2_job array
Side-Effects: none
Returns:
drmaa2_string - returns session name from drmaa2_job array
drmaa2_error drmaa2_jarray_hold (drmaa2_jarray ja)
drmaa2_jarray_hold - holds the drmaa2_job array
Parameters:
ja - pointer to drmaa2_job array
Side-Effects: none
Returns:
drmaa2_error - returns DRMAA2_SUCCESS if successful returns DRMAA2_INVALID_STATE if job state not valid for hold
drmaa2_error drmaa2_jarray_release (drmaa2_jarray ja)
drmaa2_jarray_release - releases the drmaa2_job array
Parameters:
ja - pointer to drmaa2_job array
Side-Effects: none
Returns:
drmaa2_error - returns DRMAA2_SUCCESS if successful returns DRMAA2_INVALID_STATE if job state not valid for release
drmaa2_error drmaa2_jarray_resume (drmaa2_jarray ja)
drmaa2_jarray_resume - resumes the drmaa2_job array
Parameters:
ja - pointer to drmaa2_job array
Side-Effects: none
Returns:
drmaa2_error - returns DRMAA2_SUCCESS if successful returns DRMAA2_INVALID_STATE if job state not valid for resume
drmaa2_error drmaa2_jarray_suspend (drmaa2_jarray ja)
drmaa2_jarray_suspend - suspends the drmaa2_job array
Parameters:
ja - pointer to drmaa2_job array
Side-Effects: none
Returns:
drmaa2_error - returns DRMAA2_SUCCESS if successful returns DRMAA2_INVALID_STATE if job state not valid for suspend
drmaa2_error drmaa2_jarray_terminate (drmaa2_jarray ja)
drmaa2_jarray_terminate - terminates the drmaa2_job array
Parameters:
ja - pointer to drmaa2_job array
Side-Effects: none
Returns:
drmaa2_error - returns DRMAA2_SUCCESS if successful
drmaa2_jinfo drmaa2_jinfo_create (void)
drmaa2_jinfo_create() - creates a drmaa2_job info structure and returns its pointer
Side-Effects: none
Returns:
drmaa2_jinfo - pointer to newly allocated drmaa2_jinfo structure NULL - if allocation fails and DRMAA2_OUT_OF_RESOURCE error is set
void drmaa2_jinfo_free (drmaa2_jinfo * jiRef)
drmaa2_jinfo_free() - frees the drmaa2_job info structure and its inner data types
Parameters:
jiRef - pointer to drmaa2_job info structure.
Side-Effects: none
Returns:
void
drmaa2_string_list drmaa2_jinfo_impl_spec (void)
drmaa2_jinfo_impl_spec - Lists the drmaa spec implementations supported for job info (e.g. drmaa, drmaa2)
Side-Effects: none
Returns:
drmaa2_string_list
Return values:
list of drmaa spec implementations supported
NULL - If this feature is not supported, set drmaa2_lasterror_v to DRMAA2_UNSUPPORTED_OPERATION
void drmaa2_jsession_free (drmaa2_jsession * js)
drmaa2_jsession_free Frees the memory of Job session pointed by js
Parameters:
js - pointer to drmaa2_jsession.
Side-Effects: none
Returns:
void
drmaa2_string drmaa2_jsession_get_contact (const drmaa2_jsession js)
drmaa2_jsession_get_contact - Returns the DRMS name of the drmaa2_job session
Parameters:
js - pointer to drmaa2_job session.
Side-Effects: none
Returns:
drmaa2_string - returns the DRMS name from drmaa2_jsession
drmaa2_jarray drmaa2_jsession_get_job_array (const drmaa2_jsession js, const drmaa2_string jobarrayId)
drmaa2_jsession_get_job_array - returns the specified job array from the drmaa2_job session
Parameters:
js - pointer to drmaa2_job session.
jobarrayId - Job array id which needs to be retrieved
Side-Effects: none
Returns:
drmaa2_jarray - returns pointer to drmaa2_jarray with specified jobarrayId in the job session
drmaa2_string_list drmaa2_jsession_get_job_categories (const drmaa2_jsession js)
drmaa2_jsession_get_job_categories - returns the string list of drmaa2_job categories in the drmaa2_job session
Parameters:
js - pointer to drmaa2_job session
Side-Effects: none
Returns:
drmaa2_string_list - returns list of job categories from drmaa2_jsession
drmaa2_j_list drmaa2_jsession_get_jobs (const drmaa2_jsession js, const drmaa2_jinfo filter)
drmaa2_jsession_get_jobs - returns list of jobs in the drmaa2_job session matching the jobinfo filter
Parameters:
js - pointer to drmaa2_job session js
filter - filter for getting jobs with specific conditions
Side-Effects: none
Returns:
drmaa2_j_list - returns list of jobs matching the drmaa2_job filter provided
drmaa2_string drmaa2_jsession_get_session_name (const drmaa2_jsession js)
drmaa2_jsession_get_session_name - returns the session name from drmaa2_job session.
Parameters:
js - pointer to drmaa2_job session
Side-Effects: none
Returns:
drmaa2_string - returns session name from drmaa2_jsession
drmaa2_jarray drmaa2_jsession_run_bulk_jobs (const drmaa2_jsession js_, const drmaa2_jtemplate jt_, unsigned long begin_index_, unsigned long end_index_, unsigned long step_, unsigned long
max_parallel_)
Write description of function here.
Parameters:
js_ - pointer to drmaa2_job session
jt_ - Job template to be considered or used
begin_index_ - Starting index of drmaa2_job array
end_index_ - Ending index of drmaa2_job array
step_ - Increment between each jobs
max_parallel_ - Maximum parallel jobs to run
Side-Effects: none
Returns:
drmaa2_jarray - returns pointer to drmaa2_jarray if successful returns NULL and sets last error to DRMAA2_INVALID_ARGUMENT if any argument is invalid returns NULL and sets last error to
DRMAA2_INTERNAL if any internal error occurs
drmaa2_j drmaa2_jsession_run_job (const drmaa2_jsession js_, const drmaa2_jtemplate jt_)
drmaa2_jsession_run_job - runs job in the job session with the drmaa2_job template specified
Parameters:
js_ - pointer to drmaa2_job session
jt_ - Job template that needs to be run
Side-Effects: none
Returns:
drmaa2_j - returns pointer to job which is newly started in the job session returns NULL and sets last error to DRMAA2_INVALID_ARGUMENT if any argument is invalid returns NULL and sets
last error to DRMAA2_INVALID_SESSION if session name is invalid
drmaa2_j drmaa2_jsession_wait_any_started (const drmaa2_jsession js, const drmaa2_j_list l, const time_t timeout)
drmaa2_jsession_wait_any_started - blocks till the drmaa2_job in the drmaa2_job session started or till the time out
Parameters:
js - pointer to drmaa2_job session
l - list of drmaa2_jobs
timeout - timeout to wait if event has not occurred
Side-Effects: none
Returns:
drmaa2_j - returns pointer to drmaa2_job which started returns NULL and last error is set to DRMAA2_TIMEOUT if timeout happens
drmaa2_j drmaa2_jsession_wait_any_terminated (const drmaa2_jsession js, const drmaa2_j_list l, const time_t timeout)
drmaa2_jsession_wait_any_terminated - blocks till the drmaa2_job in the drmaa2_job session ended or till the time out
Parameters:
js - pointer to drmaa2_job session
l - list of drmaa2_jobs
timeout - timeout to wait if event has not occurs
Side-Effects: none
Returns:
drmaa2_j - returns pointer to drmaa2_job which terminated returns NULL and last error is set to DRMAA2_TIMEOUT if timeout happens
drmaa2_jtemplate drmaa2_jtemplate_create (void)
drmaa2_jtemplate_create() - creates a drmaa2_job template structure and returns its pointer
Side-Effects: none
Returns:
drmaa2_jtemplate - pointer to drmaa2_jtemplate if allocated NULL - if allocation fails and DRMAA2_OUT_OF_RESOURCE error is set
void drmaa2_jtemplate_free (drmaa2_jtemplate * jtemplate)
drmaa2_jtemplate_free() - frees a drmaa2_job template structure and its inner data types
Parameters:
jtemplate - pointer to drmaa2_job template structure.
Side-Effects: none
Returns:
void
drmaa2_string_list drmaa2_jtemplate_impl_spec (void)
drmaa2_jtemplate_impl_spec - Lists the drmaa spec implementations supported for job template (e.g. drmaa, drmaa2)
Side-Effects: none
Returns:
drmaa2_string_list
Return values:
list of drmaa spec implementations supported
NULL - If this feature is not supported, set drmaa2_lasterror_v to DRMAA2_UNSUPPORTED_OPERATION
drmaa2_error drmaa2_lasterror (void)
This function returns the last occurred error.
Side-Effects: none
Returns:
drmaa2_error
drmaa2_string drmaa2_lasterror_text (void)
This function returns the last occurred error in string.
Side-Effects: none
Returns:
drmaa2_string - newly allocated string of last error NULL - If no error text exists
drmaa2_error drmaa2_list_add (drmaa2_list l, const void * value)
This function adds an element to the list.
Parameters:
l - Pointer to drmaa list
value - pointer to the element which needs to be inserted
Side-Effects: none
Returns:
drmaa2_error
Return values:
DRMAA2_INVALID_ARGUMENT DRMAA2_OUT_OF_RESOURCE DRMAA2_SUCCESS
drmaa2_list drmaa2_list_create (const drmaa2_listtype t, const drmaa2_list_entryfree callback)
This function creates a drmaa list.
Parameters:
t - Type of the list which needs to be created
callback - Call back function to call when free is called.
Side-Effects: none
Returns:
drmaa2_list
drmaa2_error drmaa2_list_del (drmaa2_list l, long pos)
This function deletes an element from the list.
Parameters:
l - Pointer to drmaa list
pos - position of the element which needs to be deleted
Side-Effects: none
Returns:
drmaa2_error
Return values:
DRMAA2_INVALID_ARGUMENT DRMAA2_SUCCESS
void drmaa2_list_free (drmaa2_list * l)
s This function frees a drmaa list
Parameters:
l - Pointer to drmaa list
Side-Effects: none
Returns:
void
const void* drmaa2_list_get (const drmaa2_list l, long index)
This function gets the element form a particular position of the list.
Parameters:
l - Pointer to drmaa list
index - postion from whcih the data has to be taken
Side-Effects: none
Returns:
void* - pointer to the element retured as void* NULL - If the position is not valid
long drmaa2_list_size (const drmaa2_list l)
This function returns the size of the list.
Parameters:
l - Pointer to drmaa list
Side-Effects: none
Returns:
long
drmaa2_machineinfo drmaa2_machineinfo_create (void)
drmaa2_machineinfo_create() - creates a drmaa2_machineinfo info structure and returns its pointer
Side-Effects: none
Returns:
drmaa2_machineinfo - pointer to newly allocated drmaa2_machineinfo structure NULL - if allocation fails and DRMAA2_OUT_OF_RESOURCE error is set
void drmaa2_machineinfo_free (drmaa2_machineinfo * miRef)
This function frees the pre-allocated drmaa machine info structure.
Parameters:
miRef - Pointer to drmaa machine info
Side-Effects: none
Returns:
void
drmaa2_string_list drmaa2_machineinfo_impl_spec (void)
drmaa2_machineinfo_impl_spec - Lists the machine info spec implementations supported
Side-Effects: none
Returns:
drmaa2_string_list
Return values:
list of machineinfo spec implementations supported
NULL - If this feature is not supported, set drmaa2_lasterror_v to DRMAA2_UNSUPPORTED_OPERATION
void drmaa2_msession_free (drmaa2_msession * ms)
drmaa2_j_list drmaa2_msession_get_all_jobs (const drmaa2_msession ms_, const drmaa2_jinfo filter_)
Returns the list of all jobs i.e. DRMAA2 jobs and the jobs submitted out of DRMAA2 library also. The list or number of jobs returned should adhere to DRMS policies. Ex: The list might be
limited to contain only the jobs seen by the DRMAA2 user.
Parameters:
ms_ - pointer to drmaa2_msession created earlier
filter_ - of type drmaa2_jinfo (through which we can query jobs per jobstate, job owner and per queue etc
Side-Effects: none
Returns:
drmaa2_j_list if succeeds NULL if fails
drmaa2_machineinfo_list drmaa2_msession_get_all_machines (const drmaa2_msession ms_, const drmaa2_string_list names_)
Returns list of machines or hosts available for submitting jobs in the DRMS system.
Parameters:
ms_ pointer to drmaa2_msession created earlier
names_ a list of queue names acts as filter i.e. we fetch info of only these queues.
Side-Effects: none
Returns:
drmaa2_machineinfo_list if succeeds NULL if fails.
drmaa2_queueinfo_list drmaa2_msession_get_all_queues (const drmaa2_msession ms_, const drmaa2_string_list names_)
Returns list of queues available for submitting jobs in the DRMS system.
Parameters:
ms_ pointer to drmaa2_msession created earlier
names_ a list of queue names acts as filter i.e. we fetch info of only these queues.
Side-Effects: none
or MT-Safe
Returns:
drmaa2_queueinfo_list if succeeds NULL if fails.
drmaa2_r_list drmaa2_msession_get_all_reservations (const drmaa2_msession ms_)
Returns the list of all advance reservations visible for the user running the DRMAA-based application. The list or number of jobs returned should adhere to DRMS policies. Ex: The list might
be limited to contain only the reservations seen by the DRMAA2 user.
Parameters:
ms_ pointer to drmaa2_msession created earlier
Side-Effects: none
Returns:
drmaa2_j_list if succeeds NULL if fails
void drmaa2_notification_free (drmaa2_notification * nRef)
This function frees the pre-allocated drmaa notification structure.
Parameters:
nRef - Pointer to drmaa notification
Side-Effects: none
Returns:
void
drmaa2_string_list drmaa2_notification_impl_spec (void)
drmaa2_notification_impl_spec - Lists the notification spec implementations supported
Side-Effects: none
Returns:
drmaa2_string_list
Return values:
list of notification spec implementations supported
NULL - If this feature is not supported, set drmaa2_lasterror_v to DRMAA2_UNSUPPORTED_OPERATION
drmaa2_jsession drmaa2_open_jsession (const char * session_name_)
drmaa2_open_jsession - Opens an already existing drmaa2_job session
Parameters:
session_name_ - Session name of the drmaa2_job session which needs to be opened
Side-Effects: none
Returns:
drmaa2_jsession - returns pointer to drmaa2_jsession for a session which is already present
drmaa2_msession drmaa2_open_msession (const char * contact_)
Opens the monitoring session.
Parameters:
contact_ - Contact of the session
Side-Effects: none
Returns:
drmaa2_msession if the session exists NULL if the session does not exist and if session name is invalid and also sets drmaa2_lasterror_v to DRMAA2_INVALID_ARGUMENT error
drmaa2_rsession drmaa2_open_rsession (const char * session_name_)
Opens the previously created session.
Parameters:
session_name_ - Name of the session.
Side-Effects: none
Returns:
drmaa2_rsession if a session exists NULL if the session does not exist and if session name is invalid and also sets drmaa2_lasterror_v to DRMAA2_INVALID_ARGUMENT error.
drmaa2_queueinfo drmaa2_queueinfo_create (void)
drmaa2_queueinfo_create() - creates a drmaa2_queueinfo structure and returns its pointer
Side-Effects: none
Returns:
drmaa2_queueinfo - pointer to newly allocated drmaa2_queueinfo structure NULL - if allocation fails and DRMAA2_OUT_OF_RESOURCE error is set
void drmaa2_queueinfo_free (drmaa2_queueinfo * qiRef)
This function frees the pre-allocated drmaa queueinfo structure.
Parameters:
qiRef - Pointer to drmaa queueinfo
Side-Effects: none
Returns:
void
drmaa2_string_list drmaa2_queueinfo_impl_spec (void)
drmaa2_queueinfo_impl_spec - Lists the queue info spec implementations supported
Side-Effects: none
Returns:
drmaa2_string_list
Return values:
list of queueinfo spec implementations supported
NULL - If this feature is not supported, set drmaa2_lasterror_v to DRMAA2_UNSUPPORTED_OPERATION
void drmaa2_r_free (drmaa2_r * r)
drmaa2_string drmaa2_r_get_id (const drmaa2_r r)
Get the reservation id from a given reservation object.
Parameters:
r - given reservation object
Side-Effects: none
Returns:
drmaa2_string
Return values:
- reservation id
drmaa2_rinfo drmaa2_r_get_info (const drmaa2_r r)
Get the reservation info from a given reservation object.
Parameters:
r - given reservation object
Side-Effects: none
Returns:
drmaa2_rinfo
Return values:
- reservation info object
drmaa2_rtemplate drmaa2_r_get_reservation_template (const drmaa2_r r)
Get the reservation template from a given reservation object.
Parameters:
r - given reservation object
Side-Effects: none
Returns:
drmaa2_rtemplate
Return values:
- reservation template
drmaa2_string drmaa2_r_get_session_name (const drmaa2_r r)
Get the reservation session name from a given reservation object.
Parameters:
r - given reservation object
Side-Effects: none
Returns:
drmaa2_string
Return values:
- reservation session name
drmaa2_error drmaa2_r_terminate (drmaa2_r r)
Terminate a given reservation.
Parameters:
r - given reservation object
Side-Effects: none
Returns:
drmaa2_error
Return values:
DRMAA2_SUCCESS
DRMAA2_DENIED_BY_DRMS
drmaa2_error drmaa2_register_event_notification (const drmaa2_callback callback)
Registers a drmaa2_callback with the DRMS library. For the first phase of implementation we do not support this.
Parameters:
callback - a structure of type drmaa2_callback containing the details of callback function, event etc
Side-Effects: none
Returns:
DRMAA2_UNSUPPORTED_OPERATION error if fails DRMAA2_SUCCESS if succeeds
drmaa2_rinfo drmaa2_rinfo_create (void)
drmaa2_rinfo_create() - creates a drmaa2_reservation info structure and returns its pointer
Side-Effects: none
Returns:
drmaa2_rinfo - pointer to newly allocated drmaa2_rinfo structure NULL - if allocation fails and DRMAA2_OUT_OF_RESOURCE error is set
void drmaa2_rinfo_free (drmaa2_rinfo * riRef)
This function frees the pre-allocated drmaa rinfo structure.
Parameters:
riRef - Pointer to drmaa reservation info
Side-Effects: none
Returns:
void
drmaa2_string_list drmaa2_rinfo_impl_spec (void)
Lists the drmaa spec implementations supported for reservation info (e.g. drmaa, drmaa2)
Side-Effects: none
Returns:
drmaa2_string_list
Return values:
list of drmaa spec implementations supported
NULL - If this feature is not supported, set drmaa2_lasterror_v to DRMAA2_UNSUPPORTED_OPERATION
void drmaa2_rsession_free (drmaa2_rsession * rs)
drmaa2_rsession_free Frees the memory of Reservation session pointed by rs
Parameters:
rs - pointer to drmaa2_rsession.
Side-Effects: none
Returns:
void
drmaa2_string drmaa2_rsession_get_contact (const drmaa2_rsession rs)
Get the contact of a given drmaa2 reservation session.
Parameters:
rs - given reservation session
Side-Effects: none
Returns:
drmaa2_string
Return values:
- contact name associated with reservation session
NULL - if reservation session is invalid, drmaa2_lasterror_v set to DRMAA2_INVALID_SESSION
drmaa2_r drmaa2_rsession_get_reservation (const drmaa2_rsession rs, const drmaa2_string reservationId)
Get the reservation object from a specific reservation session with the given reservation id.
Parameters:
rs - given reservation session
reservationId - given reservation id
Side-Effects: none
Returns:
drmaa2_r
Return values:
- reservation interface
NULL - if reservation session is invalid, drmaa2_lasterror_v set to DRMAA2_INVALID_SESSION
· if reservation id is invalid, drmaa2_lasterror_v set to DRMAA2_INVALID_ARGUMENT
drmaa2_r_list drmaa2_rsession_get_reservations (const drmaa2_rsession rs_)
Get all the reservation objects from a specific reservation session.
Parameters:
rs_ - given reservation session
Side-Effects: none
Returns:
drmaa2_r_list
Return values:
- reservation interface list
NULL - if reservation session is invalid, drmaa2_lasterror_v set to DRMAA2_INVALID_SESSION
drmaa2_string drmaa2_rsession_get_session_name (const drmaa2_rsession rs)
Get the session name of a given drmaa2 reservation session.
Parameters:
rs - given reservation session
Side-Effects: none
Returns:
drmaa2_string
Return values:
- session name associated with reservation session
NULL - if reservation session is invalid, drmaa2_lasterror_v set to DRMAA2_INVALID_SESSION
drmaa2_r drmaa2_rsession_request_reservation (const drmaa2_rsession rs, const drmaa2_rtemplate rt_)
Creates a reservation object in a specific reservation session with the given reservation template. it also evaluates reservation template for the mandatory attributes and sends the request
to DRMS.
Parameters:
rs - given reservation session
rt_ - given reservation template
Side-Effects: none
Returns:
drmaa2_r
Return values:
- reservation interface
NULL - if reservation session is invalid, drmaa2_lasterror_v set to DRMAA2_INVALID_SESSION
· if reservation template evaluation fails, drmaa2_lasterror_v set to DRMAA2_UNSUPPORTED_ATTRIBUTE
· if DRMS rejects reservation request, drmaa2_lasterror_v set to DRMAA2_DENIED_BY_DRMS
drmaa2_rtemplate drmaa2_rtemplate_create (void)
This function frees the pre-allocated drmaa rtemplate structure.
Side-Effects: none
Returns:
drmaa2_rtemplate
void drmaa2_rtemplate_free (drmaa2_rtemplate * rt)
This function frees the pre-allocated drmaa rtemplate structure.
Parameters:
rt - Pointer to drmaa rtemplate
Side-Effects: none
Returns:
void
drmaa2_string_list drmaa2_rtemplate_impl_spec (void)
Lists the drmaa spec implementations supported for reservation template (e.g. drmaa, drmaa2)
Side-Effects: none
Returns:
drmaa2_string_list
Return values:
list of drmaa spec implementations supported
NULL - If this feature is not supported, set drmaa2_lasterror_v to DRMAA2_UNSUPPORTED_OPERATION
drmaa2_error drmaa2_set_instance_value (void * instance, const char * name, const char * value)
void drmaa2_slotinfo_free (drmaa2_slotinfo * siRef)
This function frees the pre-allocated drmaa slotinfo.
Parameters:
siRef - Pointer to drmaa slotinfo
Side-Effects: none
Returns:
void
void drmaa2_string_free (drmaa2_string * str)
This function frees the previously allocated drmaa2_string.
Parameters:
str - pointer to pre allocated drmaa2_string
Side-Effects: none
Returns:
void
drmaa2_bool drmaa2_supports (const drmaa2_capability c)
drmaa2_supports - returns true if drmaa supports the provided drmaa2_capability
Parameters:
c - drmaa2_capability enum value
Side-Effects: none
Returns:
drmaa2_version
void drmaa2_version_free (drmaa2_version * vRef)
This function frees the pre-allocated drmaa version structure.
Parameters:
vRef - Pointer to drmaa version
Side-Effects: none
Returns:
void
Sample Example
drmaa2_jsession js; /* Job session object*/
drmaa2_jtemplate jt; /* Job session template*/
drmaa2_j j; /* Job object*/
...
...
...
/* Create and open job session */
js = drmaa2_create_jsession("testsession", DRMAA2_UNSET_STRING);
if (js == NULL) {
...
return;
}
...
...
...
/* Create job template */
jt = drmaa2_jtemplate_create();
jt->remoteCommand = strdup("/bin/date");
j = drmaa2_jsession_run_job(js, jt);
...
...
drmaa2_j_wait_terminated(j, DRMAA2_INFINITE_TIME);
drmaa2_jtemplate_free(&jt);
drmaa2_destroy_jsession("testsession");
...
...
...
drmaa2_j_free(&j);
drmaa2_jsession_free(&js);
...
...
...
...
...
...
drmaa2_jtemplate jt = drmaa2_jtemplate_create(); /* job template object */
drmaa2_rtemplate rt = drmaa2_rtemplate_create(); /* reservation template object */
drmaa2_string_list cl = drmaa2_list_create(DRMAA2_STRINGLIST, NULL); / *create list of strings */
drmaa2_dict env = drmaa2_dict_create(NULL); /* create a dictionary */
drmaa2_jsession js = drmaa2_create_jsession("myjsession", NULL); /* open sessions to DRM system */
if (js == NULL) {
...
...
return;
}
drmaa2_rsession rs = drmaa2_create_rsession("myrsession", NULL); /* create a reservation session */
if (rs == NULL)
{
...
...
return;
}
drmaa2_msession ms = drmaa2_open_msession(NULL); /*create and open monitoring session */
ml = drmaa2_msession_get_all_machines(ms, DRMAA2_UNSET_LIST); /* determine name of first machine */
if (drmaa2_list_size(ml) < 1) {
...
return;
}
m = (drmaa2_machineinfo)drmaa2_list_get(ml, 0);
drmaa2_list_add(cl, m->name);
rt->maxSlots = 4; /* perform advance reservation */
...
rt->machineOS=DRMAA2_LINUX;
rt->candidateMachines = cl;
r = drmaa2_rsession_request_reservation(rs, rt);
jt->remoteCommand = strdup("/bin/date"); /* submit job */
jt->reservationId = drmaa2_r_get_id(r);
drmaa2_dict_set(env, "PBS_SCP", "/usr/bin/scp");
jt->jobEnvironment = env;
j = drmaa2_jsession_run_job(js, jt);
drmaa2_j_wait_terminated(j, DRMAA2_INFINITE_TIME); /* Wait for termination and print exit status */
ji = drmaa2_j_get_info(j);
...
...
...
/* close sessions, cleanup */
drmaa2_jtemplate_free(&jt);
drmaa2_rtemplate_free(&rt);
drmaa2_jinfo_free(&ji);
drmaa2_j_free(&j);
drmaa2_r_free(&r);
drmaa2_close_msession(ms);
drmaa2_close_rsession(rs);
drmaa2_close_jsession(js);
drmaa2_msession_free(&ms);
drmaa2_rsession_free(&rs);
drmaa2_jsession_free(&js);
...
...
Questions
Not Doing
References