mirror of
https://github.com/ddidderr/wuffs.git
synced 2026-11-17 16:32:11 +01:00
Elaborate doc/note/initialization.md
This commit is contained in:
1 parent
b45b28daf8
commit
73f0f28815
1 file changed
+52
-15
+52
-15
@@ -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
|
||||
|
||||
Reference in new issue
Block a user