wash/mango
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

obj: object header is no longer allocated automatically

Browse Source
This commit is contained in:
max 🍓
2023-05-06 19:48:14 +01:00
parent 79c30e5393
commit f52ca2f1e2
13 changed files with 97 additions and 66 deletions
Download Patch File Download Diff File Expand all files Collapse all files

37
doc/objects.rst
View File

@@ -21,15 +21,15 @@ An object is made up of two distinct halves: the **header** and the
system, while the data is the programmer-defined part of the object,
and can be used however the object-creator wants.
Object behaviour is defined by an `object_type_t` instance.
An `object_type_t` provides the object system with all the information
Object behaviour is defined by a `struct object_type` instance.
A `struct object_type` provides the object system with all the information
it needs to instantiate and interact with your objects.
The Object Header
-----------------
The object header is defined in `include/socks/object.h` as `object_t`.
The object header is defined in `include/socks/object.h` as `struct object`.
It contains information that is used by the object system, and typically
should not be directly accessed outside of the object system.
@@ -37,10 +37,10 @@ The contents of the object header include:
* `ob_magic`: A magic value used to identify active objects.
Functions that retrieve an object's header from its data (and vice versa)
do not have type checking (i.e. they convert between `object_t *` and `void *`
do not have type checking (i.e. they convert between `struct object *` and `void *`
using simple pointer arithmetic), so checking for this magic number helps
protect against non-objects being passed to functions expecting objects.
* `ob_type`: A pointer to the `object_type_t` that was used to create the
* `ob_type`: A pointer to the `struct object_type` that was used to create the
object. Outside of the object system, this can be used as a read-only
way to query type information about an object.
* `ob_lock`: A general-purpose per-object lock. This lock is *not* reserved
@@ -56,35 +56,24 @@ The contents of the object header include:
queue entry.
The Object Data
---------------
The object data section is the programmer-defined part of the object, and
can be used for any purpose, although it is typically used as storage space
for a C structure. For example the data section of a `task` object is used
to store an instance of a `task_t` C structure containing the task data.
The object header and data are allocated together in a single contiguous
chunk, with the data coming after the header. **However**, you should
interactive with the object as if you don't know this. The only safe
way to convert between an object header pointer and data pointer is to
use the `object_header()` and `object_data()` functions respectively.
The object data pointer is guaranteed to be aligned on a `long` boundary.
When defining a C structure for use when creating objects, you should
define a member of type `struct object` somewhere within the structure.
It does not have to be the first member in the struct. The object system
provides a number of macros to simplify converting a `struct object *`
to a pointer of your structure.
The Object Type
---------------
The object type defines the name, size, and behaviour of an object.
It is defined using the `object_type_t` C structure.
It is defined using the `struct object_type` C structure.
Some notable parts of `object_type_t` include:
Some notable parts of `struct object_type` include:
* `ob_name`: Human-readable name of the object type. For example:
"namespace", "set", "task", etc.
* `ob_size`: The length of the data section of the object in bytes.
* `ob_cache`: An instance of `vm_cache_t` from which objects of this
* `ob_cache`: An instance of `struct vm_cache` from which objects of this
type are allocated. This cache is initialised and managed by the
object system on behalf of the programmer, so this can be ignored
outside of the object system.