diff --git a/doc/note/initialization.md b/doc/note/initialization.md index 9dc01193..a1f613bf 100644 --- a/doc/note/initialization.md +++ b/doc/note/initialization.md @@ -1,21 +1,58 @@ -# Zero Initialization +# Initialization + +Outside of the Wuffs base package, every Wuffs struct has an implicit +`initialize` method, which needs to be called before any other method. In +Wuffs' C language form, the `initialize` function for the `foo` package's `bar` +struct is called `wuffs_foo__bar__initialize`. The function takes four +arguments (or, in C++, the `initialize` method takes three arguments, with the +implicit `this` pointer argument); + +- A pointer to the `wuffs_foo__bar` object: the `this` pointer. +- The size (in bytes) of that object. Conceptually, this is + `sizeof(wuffs_foo__bar{})`, but that expression generally won't compile, as + `wuffs_foo__bar` is deliberately an incomplete type. Its size is not part of + the stable ABI. Instead, call the `sizeof__wuffs_foo__bar` *function*, whose + return value can change across Wuffs versions, even across point releases. + For an example, look for `calloc` in the + [example/library](/example/library/library.c) program. +- The Wuffs library version, `WUFFS_VERSION`. +- Additional flags. + +Initialization can fail if the caller and callee disagree on the size or the +Wuffs version, or if unsupported flag bits are passed. + +There are no destructor functions. Just free the memory. Wuffs structs don't +store or otherwise own file descriptors, pointers to dynamically allocated +memory or anything else that needs explicit releasing. + +As a consequence, to restore a Wuffs object to its initial state (e.g. to +re-use a Wuffs image decoder's memory to decode a different image), just call +the `initialize` function again. + + +## Flags + +The flags are a bitmask of options. Zero (or equivalently, +`WUFFS_INITIALIZE__DEFAULT_OPTIONS`) means that none of the options are set. + +- The `WUFFS_INITIALIZE__ALREADY_ZEROED` bit tells the `initialize` function to + assume that the entire struct has already been zero-initialized. This can + make the `initialize` call a little faster. +- The `WUFFS_INITIALIZE__LEAVE_INTERNAL_BUFFERS_UNINITIALIZED` bit means to + partially, not fully, zero-initialize the struct. Again, this can make the + call a little faster. See the "Partial Zero-Initialization" section below for + details. This bit is ignored if the `WUFFS_INITIALIZE__ALREADY_ZEROED` bit is + also set. + + +## Partial Zero-Initialization Memory-safe programming languages typically initialize their variables and fields to zero, so that there is no way to read an uninitialized value. By -default, Wuffs does so too, but in Wuffs' C/C++ form, there is the option to -leave some struct fields uninitialized (although local variables are always -zero-initialized), for performance reasons: - -``` -uint32_t flags = 0; -etc - -// Setting this flag bit takes the option. Its presence or absence has no -// effect if the WUFFS_INITIALIZE__ALREADY_ZEROED flag bit is also set. -flags |= WUFFS_INITIALIZE__LEAVE_INTERNAL_BUFFERS_UNINITIALIZED; - -wuffs_foo__bar__initialize(etc, flags); -``` +default, Wuffs does so too, but in Wuffs' C/C++ form, there is the option (the +`WUFFS_INITIALIZE__LEAVE_INTERNAL_BUFFERS_UNINITIALIZED` flag bit) to leave +some struct fields uninitialized (although local variables are always +zero-initialized), for performance reasons. With or without this flag bit set, the Wuffs compiler still enforces bounds and arithmetic overflow checks. It's just that for potentially-uninitialized struct