121 lines
4.2 KiB
ReStructuredText
121 lines
4.2 KiB
ReStructuredText
=================
|
|
THE OBJECT SYSTEM
|
|
=================
|
|
|
|
Objects are the primary means of managing and controlling access to
|
|
user-facing resources a uniform way. This document provides an
|
|
overview of the object system in the Socks kernel, including:
|
|
|
|
1. Object Layout and Definition.
|
|
2. The Object Lifecycle.
|
|
3. Object Operations and Conventions.
|
|
4. References and Handles.
|
|
5. Attributes.
|
|
|
|
|
|
Object Layout and Definition
|
|
============================
|
|
|
|
An object is made up of two distinct halves: the **header** and the
|
|
**data**. The header contains bookkeeping data used by the object
|
|
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
|
|
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`.
|
|
It contains information that is used by the object system, and typically
|
|
should not be directly accessed outside of the object system.
|
|
|
|
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 *`
|
|
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
|
|
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
|
|
for the object system to use, and can be used by the programmer. You
|
|
can lock and unlock an object by using `object_lock()` and `object_unlock()`
|
|
respectively.
|
|
* `ob_refcount` and `ob_handles`: The number of kernel references and open
|
|
handles to an object. See :ref:`References and Handles` for more details.
|
|
* `ob_attrib`: A list of attributes that are accessible for this object.
|
|
See :ref:`Attributes` for more details.
|
|
* `ob_list`: A general-purpose queue entry for adding the object to a linked
|
|
list. Note that some internal object types (such as `set`) make use of this
|
|
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.
|
|
|
|
|
|
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.
|
|
|
|
Some notable parts of `object_type_t` 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
|
|
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.
|
|
* `ob_list`: A queue entry used internally by the object system.
|
|
* `ob_attrib`: A list of object attributes defined for objects of
|
|
this type.
|
|
* `ob_ops`: A set of function pointers that are used by the object
|
|
system to interact with the object. See
|
|
:ref:`Object Operations and Conventions` for more details.
|
|
|
|
|
|
The Object Lifecycle
|
|
====================
|
|
|
|
TODO
|
|
|
|
|
|
Object Operations and Conventions
|
|
=================================
|
|
|
|
TODO
|
|
|
|
|
|
References and Handles
|
|
======================
|
|
|
|
TODO
|
|
|
|
|
|
Attributes
|
|
==========
|
|
|
|
TODO
|