mirror of
https://github.com/ddidderr/wuffs.git
synced 2026-11-18 00:32:11 +01:00
Add doc/note/statuses.md
This commit is contained in:
1 parent
2f1d5cd1dd
commit
f32ad2869c
4 files changed
+91
-38
No files matched your search
@@ -0,0 +1,88 @@
|
||||
# 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.
|
||||
- Warnings: 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. 'Warning' or 'unsuccessful' 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"`
|
||||
warning, 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 warning.
|
||||
- `'$'` means a suspension.
|
||||
- `'#'` means an error.
|
||||
|
||||
|
||||
## C Implementation
|
||||
|
||||
In terms of C implementation, a status value 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 values 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";
|
||||
```
|
||||
@@ -134,24 +134,7 @@ typedef struct {
|
||||
|
||||
// --------
|
||||
|
||||
// A status is either NULL (meaning OK) or a string message. That 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.
|
||||
//
|
||||
// Status strings are statically allocated and should never be free'd. They can
|
||||
// be compared by the == operator and not just by strcmp.
|
||||
//
|
||||
// Statuses come in four categories:
|
||||
// - OK: the request was completed, successfully.
|
||||
// - Warnings: 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 function returns an incomplete status, a suspension means that that
|
||||
// function should be called again within a new context, such as after flushing
|
||||
// or re-filling an I/O buffer. An error means that an irrecoverable failure
|
||||
// state was reached.
|
||||
// See https://github.com/google/wuffs/blob/master/doc/note/statuses.md
|
||||
typedef const char* wuffs_base__status;
|
||||
|
||||
// !! INSERT wuffs_base__status names.
|
||||
|
||||
@@ -69,8 +69,7 @@ const baseCorePublicH = "" +
|
||||
"// --------\n\n// wuffs_base__empty_struct is used when a Wuffs function returns an empty\n// struct. In C, if a function f returns void, you can't say \"x = f()\", but in\n// Wuffs, if a function g returns empty, you can say \"y = g()\".\ntypedef struct {\n // private_impl is a placeholder field. It isn't explicitly used, except that\n // without it, the sizeof a struct with no fields can differ across C/C++\n // compilers, and it is undefined behavior in C99. For example, gcc says that\n // the sizeof an empty struct is 0, and g++ says that it is 1. This leads to\n // ABI incompatibility if a Wuffs .c file is processed by one compiler and\n // its .h file with another compiler.\n //\n // Instead, we explicitly insert an otherwise unused field, so that the\n // sizeof this struct is always 1.\n uint8_t private_impl;\n} wuffs_base__empty_struct;\n\nstatic inline wuffs_base__empty_struct //\nwuffs_base__make_empty_struct() {\n wuffs_base__empty_struct ret;\n ret.private_impl = 0;\n return ret;\n}\n\n// wuffs_base__utility is" +
|
||||
" a placeholder receiver type. It enables what Java\n// calls static methods, as opposed to regular methods.\ntypedef struct {\n // private_impl is a placeholder field. It isn't explicitly used, except that\n // without it, the sizeof a struct with no fields can differ across C/C++\n // compilers, and it is undefined behavior in C99. For example, gcc says that\n // the sizeof an empty struct is 0, and g++ says that it is 1. This leads to\n // ABI incompatibility if a Wuffs .c file is processed by one compiler and\n // its .h file with another compiler.\n //\n // Instead, we explicitly insert an otherwise unused field, so that the\n // sizeof this struct is always 1.\n uint8_t private_impl;\n} wuffs_base__utility;\n\n" +
|
||||
"" +
|
||||
"// --------\n\n// A status is either NULL (meaning OK) or a string message. That message is\n// human-readable, for programmers, but it is not for end users. It is not\n// localized, and does not contain additional contextual information such as a\n// source filename.\n//\n// Status strings are statically allocated and should never be free'd. They can\n// be compared by the == operator and not just by strcmp.\n//\n// Statuses come in four categories:\n// - OK: the request was completed, successfully.\n// - Warnings: the request was completed, unsuccessfully.\n// - Suspensions: the request was not completed, but can be re-tried.\n// - Errors: the request was not completed, permanently.\n//\n// When a function returns an incomplete status, a suspension means that that\n// function should be called again within a new context, such as after flushing\n// or re-filling an I/O buffer. An error means that an irrecoverable failure\n// state was reached.\ntypedef const char* wuffs_base__status;\n\n// !! INSERT wuffs_bas" +
|
||||
"e__status names.\n\nstatic inline bool //\nwuffs_base__status__is_complete(wuffs_base__status z) {\n return (z == NULL) || ((*z != '$') && (*z != '#'));\n}\n\nstatic inline bool //\nwuffs_base__status__is_error(wuffs_base__status z) {\n return z && (*z == '#');\n}\n\nstatic inline bool //\nwuffs_base__status__is_ok(wuffs_base__status z) {\n return z == NULL;\n}\n\nstatic inline bool //\nwuffs_base__status__is_suspension(wuffs_base__status z) {\n return z && (*z == '$');\n}\n\nstatic inline bool //\nwuffs_base__status__is_warning(wuffs_base__status z) {\n return z && (*z != '$') && (*z != '#');\n}\n\n" +
|
||||
"// --------\n\n// See https://github.com/google/wuffs/blob/master/doc/note/statuses.md\ntypedef const char* wuffs_base__status;\n\n// !! INSERT wuffs_base__status names.\n\nstatic inline bool //\nwuffs_base__status__is_complete(wuffs_base__status z) {\n return (z == NULL) || ((*z != '$') && (*z != '#'));\n}\n\nstatic inline bool //\nwuffs_base__status__is_error(wuffs_base__status z) {\n return z && (*z == '#');\n}\n\nstatic inline bool //\nwuffs_base__status__is_ok(wuffs_base__status z) {\n return z == NULL;\n}\n\nstatic inline bool //\nwuffs_base__status__is_suspension(wuffs_base__status z) {\n return z && (*z == '$');\n}\n\nstatic inline bool //\nwuffs_base__status__is_warning(wuffs_base__status z) {\n return z && (*z != '$') && (*z != '#');\n}\n\n" +
|
||||
"" +
|
||||
"// --------\n\n// FourCC constants.\n\n// !! INSERT FourCCs.\n\n" +
|
||||
"" +
|
||||
|
||||
@@ -156,24 +156,7 @@ typedef struct {
|
||||
|
||||
// --------
|
||||
|
||||
// A status is either NULL (meaning OK) or a string message. That 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.
|
||||
//
|
||||
// Status strings are statically allocated and should never be free'd. They can
|
||||
// be compared by the == operator and not just by strcmp.
|
||||
//
|
||||
// Statuses come in four categories:
|
||||
// - OK: the request was completed, successfully.
|
||||
// - Warnings: 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 function returns an incomplete status, a suspension means that that
|
||||
// function should be called again within a new context, such as after flushing
|
||||
// or re-filling an I/O buffer. An error means that an irrecoverable failure
|
||||
// state was reached.
|
||||
// See https://github.com/google/wuffs/blob/master/doc/note/statuses.md
|
||||
typedef const char* wuffs_base__status;
|
||||
|
||||
extern const char* wuffs_base__warning__end_of_data;
|
||||
|
||||
Reference in new issue
Block a user