The oskit_bufio interface extends the oskit_absio interface, providing additional alternative methods of accessing the object's data. In particular, for objects whose data is stored in an in-memory buffer of some kind, this interface allows clients to obtain direct access to the buffer itself so that they can read and write data using loads and stores, rather than having to copy data into and out of the buffer using the read and write methods. In addition, this interface provides similar methods to allow clients to ``wire'' the buffer's contents to physical memory, enabling DMA-based hardware devices to access the buffer directly.
However, note that only the read/write methods, inherited from oskit_absio, are mandatory; the others may consistently fail with OSKIT_E_NOTIMPL if they cannot be implemented efficiently in a particular situation. In that case, the caller must use the basic read and write methods instead to copy the data. In other words, oskit_bufio object implementations are not required to implement direct buffer access, either software- or DMA-based; the purpose of this interface is merely to allow them to provide this optional functionality easily and consistently. In general, the map and wire methods should only be implemented if they can be done more efficiently than simply copying the data. Further, even if a buffer I/O implementation does implement map and/or wire it may allow only one mapping or wiring to be in effect at once, failing if the client attempts to map or wire the buffer a second time before the first mapping is undone. Similarly, on some buffer I/O implementations, these operations may only work on certain areas of the buffer or only when the request has certain size or alignment properties: for example, a buffer object that stores data in discontiguous segments, such as BSD's mbuf system, may only allow a buffer to be mapped if the requested region happens to fall entirely within one segment. Thus, the client of a bufio object should call the map or wire methods whenever it can take advantage of direct buffer access, but must always be prepared to fall back to the basic copying methods.
A particular buffer object may be semantically read-only or write-only; it is assumed that parties passing bufio objects around will agree upon this as part of their protocols. For a read-only buffer, the write method may or may not fail, and a mapping established using the map method may or may not actually be a read-only memory mapping; it is the client's responsibility not to attempt to write to the buffer. Similarly, for a write-only buffer, the read method may or may not fail; it is the client's responsibility not to attempt to read from the buffer.
The oskit_bufio interface extends the oskit_absio interface with the following additional methods: