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)
