diff --git a/doc/note/statuses.md b/doc/note/statuses.md new file mode 100644 index 00000000..0a48cfc4 --- /dev/null +++ b/doc/note/statuses.md @@ -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"; +``` diff --git a/internal/cgen/base/core-public.h b/internal/cgen/base/core-public.h index 5128728d..67681e25 100644 --- a/internal/cgen/base/core-public.h +++ b/internal/cgen/base/core-public.h @@ -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. diff --git a/internal/cgen/data.go b/internal/cgen/data.go index 29e7c7e0..d097061d 100644 --- a/internal/cgen/data.go +++ b/internal/cgen/data.go @@ -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" + "" + diff --git a/release/c/wuffs-unsupported-snapshot.c b/release/c/wuffs-unsupported-snapshot.c index 8fb3b69b..cccf291c 100644 --- a/release/c/wuffs-unsupported-snapshot.c +++ b/release/c/wuffs-unsupported-snapshot.c @@ -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;