meta: rename

doc/objects.rst

@@ -1,109 +0,0 @@
-=================
-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