[DRMAA-WG] DRMAAv2 C binding - General style decision

[Peter Tröger]

Dear all,

in continuation of the conf call discussion, I asked Andre for a summary 
of the API style possibilities in the C binding. We currently have a 
model were the C equivalent of an IDL function is returning a typed 
result value, while the C equivalent of an IDL procedure is returning a 
typed error code:

drmaa2_job_template_t drmaa2_j_get_job_template (drmaa2_job_h j);
drmaa2_error_t        drmaa2_j_suspend (drmaa2_job_h j);

Here is Andre's statement:

--- snip ---

IIRC, the assumption was that we need to always be able to determine an
error condition.  For example:

   drmaa2_job_info_t drmaa2_job_info_create (void);
   drmaa2_error_t    drmaa2_job_info_free   (drmaa2_job_info_t ji);

The create can of course fail.  In that case, the error will be
signaled by returning a NULL pointer -- remember that

   typedef drmaa2_job_info_s * drmaa2_job_info_t

The free call is, in idl, void, and thus could not flag an error.
Thus we made it return that flag explicitly.

That is similar to what many unix calls do, for example:

   FILE * fopen(const char *path, const char *mode); // NULL on return
-> check errno
   int fseek(FILE *stream, long offset, int whence); // 0 on success,
-1 on error -> check errno

There are other options of course, which look more consistent:

  - always return an error code
    pro: very consistent
    con: cumbersome for typed return values (which have to be passed by ref)

  - always check for error afterwards (bool last_call_suceeded())
    pro: consistent, typed return vals
    con: doubles lines of code, cumbersome to use

  - always pass a error type by ref, and check afterwards
    pro: consistent, typed return vals
    con: somewhat cumbersome to use, in particular for actual void functions

It is a ll a trade-off.  Right now, I think the trade-off is somewhat
balanced, and is leaning on Posix and other C system libs, but then
again, I am biased ;-)

--- snip ---

We need to make a general decision here, Andre made the available 
options pretty clear. Please state your favorite C API style, maybe with 
some reference to other APIs using this style.

Thanks and best regards,
Peter.