1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
4
<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=iso-8859-1">
6
<META NAME="GENERATOR" CONTENT="StarOffice/5.2 (Solaris Sparc)">
7
<META NAME="AUTHOR" CONTENT=" ">
8
<META NAME="CREATED" CONTENT="20010611;14564800">
9
<META NAME="CHANGEDBY" CONTENT=" ">
10
<META NAME="CHANGED" CONTENT="20010716;16471800">
13
<H1><FONT SIZE=6 STYLE="font-size: 28pt">DRMAA C binding library for Grid Engine</FONT></H1>
15
<P>The purpose of this library is to provide an implementation of the DRMAA C binding
16
standard based on Grid Engine DRM system. The best way to describe DRMAA is to cite
17
the DRMAA-WG Charter:</P>
19
<P>"Develop an API specification for the submission and control of jobs to one or more Distributed Resource
20
Management (DRM) systems. The scope of this specification is all the high level functionality which is
21
necessary for an application to consign a job to a DRM system including common operations on jobs like
22
termination or suspension.</P>
23
<P>The objective is to facilitate the direct interfacing of applications to today's DRM systems by
24
application's builders, portal builders, and Independent Software Vendors (ISVs)."</P>
26
<P>For more details on the
27
<A HREF="http://www.gridforum.org">Global Grid Forum</A>
28
standards body working group refer to the page of the
29
<A HREF="http://www.drmaa.org">GGF DRMAA working group</A>
32
<H1>Documentation</H1>
33
<P>The following DRMAA related documentation is recommended
34
<A HREF="http://www.drmaa.org/docs/ggf-rec-drmaa-1_0.pdf">DRMAA 1.0 language independent specification</A>,
35
<A HREF="https://forge.gridforum.org/tracker/?group_id=90&atid=608&aid=214">DRMAA C language binding specification</A>,
36
<A HREF="http://gridengine.sunsource.net/unbranded-source/browse/%7Echeckout%7E/gridengine/source/libs/japi/jobstates.html?content-type=text/html">Grid Engine/DRMAA job state mapping table</A>
38
<A HREF="http://gridengine.sunsource.net/unbranded-source/browse/~checkout~/gridengine/doc/htmlman/manuals.html?content-type=text/html">HTML version of Grid Engine DRMAA C binding man pages (only those in section 3 with drmaa_* prefixes)</A>
41
<P>For the current 5.3 release DRMAA is not and will not be available. For 6.0 it is planned to deliver
42
everything needed to integrate applications via DRMAA with Grid Engine including a DRMAA library that
43
can be linked dynamically. At this stage DRMAA is available as a source snapshot from the "maintrunk"
44
of the Grid Engine. To get this source snapshot you must use the cvs option "-r VMAIN_STABLE_3_TAG" when
45
you check out the sources as described under <A HREF="http://gridengine.sunsource.net/servlets/ProjectSource">Download Source</A>.</P>
47
<P>In this source snapshot the following Grid Engine binary architectures are known to be working:</P>
49
<LI><P>solaris (Sparc Solaris 2.6, 7, 8, 9 32-bit)</P>
50
><P>solaris64 (Sparc Solaris 7, 8, 9 64-bit</P>
51
<LI><P>solaris86 (x86 Solaris 8)</P>
52
><P>glinux (x86 Linux, kernel 2.4, glibc >= 2.2)</P>
54
<P>There are three build targets that are related to DRMAA:</P>
56
<LI><P>libdrmaa.a - a DRMAA library for statically linking</P>
57
<LI><P>libjapi.a - a JAPI library for statically linking</P>
58
<LI><P>test_drmaa - a test DRMAA application used for QA</P>
62
<P>The steps described in the
63
<A HREF="http://gridengine.sunsource.net/unbranded-source/browse/~checkout~/gridengine/source/README.BUILD">Grid Engine build page</A>
64
are the same that also must be followed for building the DRMAA build targets. In case of Grid Engine binary architectures where the
65
port is already done the command</P>
69
<P>compiles all regular Grid Engine binaries plus DRMAA build targets. To enforce compilation
70
of DRMAA build targets for not yet ported binary architectures
74
<P>can be used. To compile all Grid Engine binaries except the DRMAA build targets</P>
79
<P>Upon successful build the DRMAA targets are found in the "*_MT"
80
directories. Build targets in this directory are compiled in a way allowing them to be
81
used in multi-threaded applications. Due to the JAPI service thread (see implementation of
82
<A HREF="http://gridengine.sunsource.net/unbranded-source/browse/%7Echeckout%7E/gridengine/source/libs/japi/japi.html?content-type=text/html">JAPI library</A>
83
) this is necessary for major parts of the code that implements DRMAA. For the same reason a
84
good amount of Grid Engine source code has been reworked to make it reentrant (where possible)
85
or at least thread safe. As result of this effort MT safe functions are marked with comments
89
MT-NOTE: sge_gdi() is MT safe
91
<P>it is important to understand that with all these comments major assumptions were
92
made. The current major assumptions are</P>
94
<LI><P>code was not compiled with aimk option -DCOMMCOMPRESS</P>
95
<LI><P>code was not compiled with aimk option -DCRYPTO</P>
96
<LI><P>code was not compiled with aimk option -DKERBEROS</P>
97
<LI><P>code was not compiled with aimk option -SECURE</P>
98
<LI><P>if the code was compiled with aimk option -SECURE then
99
only non-secure may be used</P>
100
<LI><P>neither AFS nor DCE/KERBEROS security may be used</P>
101
<LI><P>system is not used in I18N mode</P>
103
<P>if these assumptions are not met DRMAA library can not be expected to be working
104
properly and will crash most probably! To overcome those constraints it is necessary
105
firstly to link Grid Engine against the corresponding MT safe libraries (zlib,
106
openssl, ...). Secondly those parts of the Grid Engine source code that makes use of
107
those libraries must be reviewed and changed were necessary.</P>
108
<H1>Example application</H1>
109
<P>The C test program
110
<A HREF="http://gridengine.sunsource.net/source/browse/gridengine/source/libs/japi/example.c">example.c</A>
111
is a good example of an application that uses the DRMAA C binding interface.
112
It illustrates submission of both single and bulk remote jobs. After submission drmaa_synchronize() call
113
is used to synchronize the remote jobs execution. The call returns after all the jobs have finished
114
executing. Finally, drmaa_wait() call is used to retrieve and print out the remote jobs' execution
116
<P>A full path for the remote command is passed as the first argument to the test program.
117
That value is directly used as "drmaa_remote_command" job template attribute. The C binding example uses
118
value "5" as a first argument to the job template vector attribute "drmaa_v_argv". Passing "/bin/sleep" as
119
a first argument to the test program will for example cause 32 sleep jobs to be run that sleep for "5"
120
seconds each before finishing execution. Note that we expect to find "/bin/sleep" command on all of the
122
<P>To build this example run
126
This is necessary because "example" is not part of the standard build procedure.</P>
128
You can file bugs to Grid Engine Issuezilla "drmaa" subcomponent. Before doing so please have a
129
look at the TODO list below and watch out for already submitted "drmaa" bugs. If you're not sure
130
whether you found a bug sending mail to
131
<A HREF="http://gridengine.sunsource.net/project/gridengine/maillist.html">dev@gridengine.sunsource.net Mailinglist</A>
133
<H1>Notes on implementation</H1>
134
<P>The Grid Engine implementation of DRMAA bases on Grid Engine
135
<A HREF="http://gridengine.sunsource.net/unbranded-source/browse/%7Echeckout%7E/gridengine/source/libs/japi/japi.html?content-type=text/html">Job API library (JAPI)</A>
136
. As a result DRMAA library inherits MT safety from JAPI library.</P>
137
<P>Interfaces operations of Grid Engine JAPI library and DRMAA library have lots in common.
138
The big difference amongst them is that JAPI allows any characteristic of the Grid Engine job
139
that is submitted through JAPI be influenced, whereas DRMAA allows only those characteristics be influenced that
140
are interfaced by DRMAA. Note that this ostensible drawback of DRMAA library is not as meaningful as it seems:
141
Firstly DRMAA job template attributes "drmaa_job_category" and "drmaa_native_specification" will allow nearly all
142
of the qsub(1) job characteristics be influenced. Secondly by building an integration upon DRMAA library you
143
don't need to change your application code each time when a new Grid Engine version is released. When using JAPI
144
library interface you must be prepared to change your application code in this case. This is because JAPI directly
145
exports Grid Engine internal data structures that usually are subject of change with new releases.</P>
146
<H1>Grid Engine DRMAA library QA</H1>
147
<P>The DRMAA application "test_drmaa" is used by Grid Engine testsuite QA tool to ensure quality of DRMAA
148
library. It covers a growing number of tests. There are so-called standalone tests that can
149
be accomplished autonomously by the test_drmaa application. To run all these tests standalone "test_drmaa"
150
can be started with the "ALL_AUTOMATED" option plus some option arguments. To run all
151
DRMAA related tests so far implemented choose "api/drmaa" in testsuite and have testsuite do the work for you.</P>
152
<P ALIGN=CENTER STYLE="text-decoration: none">Copyright 2003 Sun Microsystems, Inc. All rights reserved.</P>