[doc] Missing Documentation for Error Codes

[mgravell]

Context

If we refer to https://github.com/demikernel/demikernel/blob/dev/man/demi_pop.md, for example, we see:

• EBADF - The I/O queue descriptor qd does not refer to a valid I/O queue.
• EAGAIN - Demikernel failed to create an asynchronous co-routine to handle the demi_pop() operation.

As an external caller: what are those values?

Proposed Solution

When specific error codes should be anticipated, document the corresponding literal integer values, since that is what an external consumer needs to know. Obviously we can interpret any non-zero number as a general error, but: the ability to understand more-specific errors would be useful.

It would be sufficient to link to a shared list of error codes, rather than updating every page individually.

[ppenna]

@mgravell the literal values for these error codes are platform dependent. They match whatever value the underlying OS uses in #include <errno.h>. I understand that you are suggesting that we ship our own error codes. Is that the case?

[mgravell]

@ppenna I suspect "yes"; external API consumers need to bind to something fixed - when calling between languages, runtimes, etc, with different build times and infrastructure, it is otherwise going to be impossible (or at least, exceptionally hard) to know how to interpret any given integer. We can't even rely on "non-zero? just explode", since the wait API now returns a specific number to mean "I timed out". Right now I've hard-coded that via manual discovery of what number I got, but that doesn't work in the general sense, if those numbers aren't fixed.

External API consumers are going to need to know what error code that timeout is, without knowing your build infrastructure. Likewise other error messages, although they're probably less critical if they all mean "something bad". As a corollary: maybe timeout shouldn't be an error? Maybe timeout should return 0 but signal the timeout via another mechanism. For example, it could return -1 in the offset parameter. Or with #341 in mind, return ~offset for whatever offset it was looking at (which would still allow timeout to be identified as a negative, while also allowing the offset to be retained between calls)

[mgravell]

To put that in specific terms: consider a .NET client - I would expect to ship that as a nupkg binary (with the unmanaged lib for various platforms contained internally). That binary does not have access to errno.h - the C# is typically built separately, at a separate time, probably on a CI server. I'm pretty sure this will be commonly the case among most non-C/Rust consumers.

[ppenna]

@iyzhang , @BrianZill and @anandbonde please take a look on this.

[BrianZill]

I agree, we should have our own error codes, independent of platform.

[iyzhang]

Hi Marc, thanks for filing this. We are tabling this for now because we do not have any customers that require this and we do not have the wo(man) power to revise our error codes at this time. We do have the infrastructure in place to change them in the future however because we do have our own Rust fail data structure that we could move to a custom error code system.