whio  Artifact Content

Artifact fa94dc64c2a9b47ee53b957c0eead6565c065cbf:

Wiki page [whio_dev] by stephan 2011-05-23 18:50:53.
D 2011-05-23T18:50:53.863
L whio_dev
P 777a2b7c68f41712acf3140a66066c265132f0fb
U stephan
W 2788
<strong>ACHTUNG: AS OF 20110523, THIS PAGE IS NOW MAINTAINED IN THE NEW WIKI:</strong> [http://whiki.wanderinghorse.net/wikis/whio/?page=whio_dev]


<h1>whio_dev API</h1>

whio_dev is a C struct (declared in <tt>&lt;wh/whio/whio_dev.h&gt;</tt>) which defines an interface for basic random-access i/o operations. It essentially defines the same functionality as are available for standard FILE handles.

whio_dev specifies only an interface, and instances of concrete implementations are created via various factory functions (declared in <tt>&lt;wh/whio/whio_devs.h&gt;</tt>). Probably its most useful feature is that all i/o devices are destroyed using the same interface - only their construction is type-specific. This simplifies clean-up in client code, e.g. compared to having to know whether a give <tt>FILE</tt> handle must be closed with <tt>fclose(3)</tt> or <tt>pclose(3)</tt>.

Implementations are provided for the following types of i/o devices:

  *  Local files, either by filename, <tt>FILE</tt> handle, or file descriptor. There are various methods for opening them, depending on what interface you prefer to use (e.g. using <tt>open(2)</tt>-style arguments or <tt>fopen(3)</tt>-style). For files there are two different implementations - one uses the low-level <tt>read(2)/write(2)</tt> interfaces and one uses the higher-level <tt>FILE</tt> abstraction.
  *  A dynamically-allocated memory buffer which grows as the device grows.
  *  A bounded, user-supplied memory range, either in read-write or read-only modes.
  *  The "subdevice" class acts as a proxy for a client-defined range of bytes within another (parent) device. Subdevices are used to fence access to a certain range of bytes within the parent (a subdevice won't let the user write past its logical end), and subdevices can be nested within other subdevices.
  *  The [whio_epfs] bits support "embedded" files which the client interacts with via the whio_dev interface. (It also uses whio_dev as the back-end storage, which means that one EPFS can be embedded in another.)

In principal, it is normally simple to create whio_dev implementations for any type of device which provides facilities for random access. In doing so, any generic i/o algorithms, or code which uses the whio_dev interface for its i/o, can use such client-supplied whio_dev implementations. For example, [whio_epfs] and [whio_udb] can use any compliant client-written device for their underlying storage.

<h2>See also...</h2>

  *  [whio_stream], an interface for sequential-only device access.
  *  [whio_epfs], an embedded filesystem based on the whio_dev API.
  *  [whio_udb], a whio_dev-base hashtable.
  *  [whio_ht], another whio_dev-base hashtable.
  *  [whio_vlbm], a storage-based "memory allocator."

Z ad5d0a23af92a765168af732441f0d45