[drmaa-wg] C binding data structures

[Andreas Haas]

On Thu, 11 Aug 2005, Cargnelli, Matthieu wrote:

> Hello,
>
> Sorry for these questions that will probably look a little dumb, but I
> just can't figure it out.

No worries! I'm happy to see you do writing DRMAA for OpenPBS/Torque.

> I hope this is the right place to ask these
> questions...

Well, kind of.

>
> I'm trying to write a DRMAA C binding for Torque/OpenPBS. I've read the
> drmaa C binding documents and some of this mailing list archive, but
> couldn't find an answer.
>
> I was defining a job_template structure containing the necessary
> strings, something like this:
> struct drmaa_job_template_s
> {
>   char* drmaa_remote_command;
>   char* drmaa_js_state;
>   char* drmaa_wd;
>   [...]
> };
>
> But eventually I thought that it would rather be something like:
> struct drmaa_job_template_s
> {
>   drmaa_attr_names_t* _attr_names;
>   drmaa_attr_values_t* _attr_values;
>   [...]
> };
> that should be implemented (at least that would justify the opaque
> string vectors).
>
> Could someone please shed some light on this matter please? I'm really
> unable to find that information anywhere.

The drmaa.h should contain an opaque typedef based on a pure
struct declaration

   typedef struct drmaa_job_template_s drmaa_job_template_t;

the struct definition is kept in a file other than drmaa.h to ensure
the sizeof(drmaa_job_template_t) is not known by DRMAA applications.
E.g. in case of Grid Engine it's a

   struct drmaa_job_template_s {
      lList *strings;
      lList *string_vectors;
   };

and resides in implementation file japiP.h. Hiding sizeof() a data type
is common technicque in C to ensure allocator/descructor functions are
always used for obtaining/destroying opaque data structures. If this
is guaranteed one can change struct definition at any time in the
implementation without fear to any influence on the DRMAA application.

> Besides, what are we supposed to put in the opaque string vectors if the
> first case apply?
>
> In both cases how are we supposed to make the relation between the
> attr_name vector and the attr_value vector? I suppose these actually
> contain pairs of value. But as they can only be accessed by
> drmaa_get_next_attr_name and drmaa_get_next_attr_ value functions, is
> the user condamned to use alternatively get_next_name and get_next_value
> functions to be certain he gets the proper value for the proper
> attribute name?

Use of drmaa_attr_names_t* for struct drmaa_job_template_s definition as you
envision above might be possible (I haven't checked thoroughly) but at least
was not intended. I'd assume use of PBS specific data types should be favoured,
but. Finally it is up to you what you decide to use for this purpose since
struct drmaa_job_template_s definition wasn't made part of DRMAA specification
by intent. Note the "lList *" data type above is a Grid Engine implementation
specific data type that is related by no means to DRMAA.

>
> Finaly, that leads to the function:
> /*
>  * Adds ('name', 'value') pair to list of attributes in job template 'jt'.
>  * Only non-vector attributes may be passed.
>  */
> int drmaa_set_attribute(drmaa_job_template_t *jt, const char *name,
> const char *value, char *error_diagnosis, size_t error_diag_len);
>
> If I'm correct, this function would add (or modify) one element to
> attr_name and one to attr_value string vectors... Or am I totally wrong
> about it ?

If PBS implementation uses a struct drmaa_job_template_s definition
as in your second example above this is what it would do.

Regards,
Andreas

Sun Microsystems GmbH       |            ++49 +941 3075-131
Dr.-Leo-Ritter-Str. 7       |                N1 Grid Engine
D-93049 Regensburg/Germany  | System Engineering Group Lead