=================
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