mirror of
https://github.com/ddidderr/wuffs.git
synced 2026-11-17 16:32:11 +01:00
93 lines
3.2 KiB
Markdown
93 lines
3.2 KiB
Markdown
# Statuses
|
|
|
|
Wuffs' important functions - ones that do a significant amount of work, often
|
|
involving [I/O](/doc/note/io-input-output.md) - 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](/doc/glossary.md#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](/doc/note/coroutines.md) 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 `free`d. Status `repr`s 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
|
|
`'$'`.
|