Statuses

Wuffs' important functions - ones that do a significant amount of work, often involving I/O - return a status value. There are four categories:

• OK: the request was completed, successfully.
• Notes: the request was completed, unsuccessfully.
• Suspensions: the request was not completed, but can be re-tried.
• Errors: the request was not completed, permanently.

When a method returns an error, it is permanent. Calling that method (or any other status-returning method), on the same receiver, will return a "#disabled by previous error" error.

When a method returns a suspension, the suspended coroutine can be resumed by calling that method again. However, calling any other public coroutine method, while already suspended, will lead to an "#interleaved coroutine calls" error.

Otherwise, the call was complete. ‘Unsuccessful’ (i.e. a note) doesn‘t necessarily mean ‘bad’ or something to avoid, only that something occurred other than the typical outcome. For example, when decoding an animated image, without knowing the number of frames beforehand, a call to “decode the next frame” could return OK, if there was a next frame, or an "@end of data" note, if there wasn’t.

Statuses are Strings

There is only one value in the OK category. In Wuffs code, this is a built-in literal value called ok, without " quote marks. For example:

return ok

The other categories can contain multiple values, each with an ASCII string message. In Wuffs code, a string literal is synonymous with a status value, as Wuffs otherwise doesn't use string-typed values, only byte slices, arrays and buffers:

// Return an error status, defined in this package.
return "#bad Huffman code"

That status value may be package-qualified. For example, a coroutine could refer to a status defined in another package, base:

// Yield a suspension status, defined in the base package.
yield? base."$short read"

That string message is human-readable, for programmers, but it is not for end users. It is not localized, and does not contain additional contextual information such as a source filename.

The first byte of the string message gives the category. For example, "#bad receiver" is an error and "$short read" is a suspension:

• '@' means a note.
• '$' means a suspension.
• '#' means an error.

C Implementation

In terms of C implementation, a status' repr (representation) is just its string message: a const char *, with ok being the null pointer. That C string is statically allocated and should never be freed. Status reprs can be compared by the == operator and not just by strcmp.

The C string's contents has the Wuffs package name inserted by the Wuffs compiler, just after that first byte. For example, the std/deflate package has this line of Wuffs code, defining an error status:

pub status "#bad Huffman code"

When that Wuffs code is compiled to C, it produces:

const char* wuffs_deflate__error__bad_huffman_code =
    "#deflate: bad Huffman code";

When printing a status message, the wuffs_base__status__message function will advance a (non null) pointer by 1 byte, skipping that leading '@', '#' or '$'.