[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.