Elaborate doc/note/initialization.md

This commit is contained in:
Nigel Tao committed 2019-11-22 20:56:35 +11:00
1 parent b45b28daf8
commit 73f0f28815
1 file changed
+52 -15
+52 -15
View File
@@ -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