[pulseaudio-discuss] [PATCH 0/4] Error handling and its documentation in the public API

[Peter Meerwald]

Hello Tanu,

> I have started to go through all functions in the public API
> (currently 359 functions - this will take some time),
> prompted by the discussion that started from this patch:
> http://lists.freedesktop.org/archives/pulseaudio-discuss/2011-December/012412.html

thank you for picking up the idea; my original intention was a lot more 
modest than checking and improving the entire API: I just wanted to state 
how error information is handled in the PA API

I am working on a simple statement to go into the doxygen for 
pulseaudio.h, here's my current draft:

+ * \section error_sec Error Handling
+ *
+ * The PulseAudio API indicates error conditions by returning a negative
+ * integer value or a NULL pointer. On success, a positive integer value
+ * or a valid pointer is returned.
+ *
+ * Functions of the \ref simple generally return -1 or NULL on failure and
+ * can optionally store an error code (see ::pa_error_code) using a pointer
+ * argument.
+ *
+ * Functions of the \ref async return an negative error code or NULL on
+ * failure (see ::pa_error_code). In the later case, pa_context_errno() 
+ * can be used to obtain the error code of the last failed operation.
+ *
+ * An error code can be turned into a human readable message using
+ * pa_strerror().
+ *

> Instead of waiting until I'm finished with all patches, I'll
> send the first patches already now in case there are
> comments regarding the overall goals. I intend to make sure
> that each function documents how (non-programmer) errors are
> reported to the caller.

I think we should first agree on the general description (see my 
suggestion above)

here is a list of my concerns:

- is it error code (e.g. def.h), error value or error number (e.g. 
pa_context_errno())?

- functions may indicate an error condition without setting 
context error (does it happen?);

- functions may set the context errno without indicating an error 
condition to the caller (does it happen?); related question: how long is 
context errno valid?
one could state something like (taken from errno(3)):
"Its value is significant only when the return value of the call indicated 
an error; a function that succeeds is allowed to change errno."

- does the following hold?

int ret = pa_foo();
if (ret < 0)
  assert(ret == -pa_context_errno(c));

> I also intend to make sure that no function in the public
> API returns a generic -1 as the return value to represent
> error (unless explicitly documented). When errors are
> reported using a negative number, the number should be
> suitable for passing to pa_strerror(). pa_strerror() maps -1
> to "Access denied", which usually is very misleading.

agree; interestingly pa_strerror() accepts both positive and negative 
values

coming from the Simple API at first, I found the different error handling 
semantics for the Async API quite confusing

Simple API .. -1 on error
Async API .. -errno

regards, p.

-- 

Peter Meerwald
+43-664-2444418 (mobile)