110 lines
3.8 KiB
ReStructuredText
110 lines
3.8 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 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 `struct object`.
|
|
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 `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 `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
|
|
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.
|
|
|
|
|
|
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 `struct object_type` C structure.
|
|
|
|
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 `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.
|
|
* `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
|