Fastbufs
========

A *fastbuf* is a stream (or file) abstraction optimized for both speed
and flexibility.

Fastbufs can represent many different kinds of objects: regular files, network
sockets, file descriptors in general, or various memory buffers. These objects
are handled by different fastbuf *back-ends.*

Once you have a fastbuf, you can access it by functions similar to those of
`stdio.h`, or you can use a variety of fastbuf *front-ends* providing various
formatted operations.

There are also fastbuf *wrappers*, which serve as both back-ends and front-ends,
taking one stream and converting it to another on the fly.

Please keep in mind that fastbufs do not allow arbitrary mixing of reads and
writes on the same stream. If you need to mix them, you have to call @bflush()
inbetween and remember that the file position reported by @btell() points after
the flushed buffer, which is not necessarily the same as after the data you've
really read.

Fastbufs can also participate in the libucw resource management system.
You can tie a fastbuf to a resource in the current resource pool by @fb_tie().
When the pool gets cleaned up, the fastbuf is automatically closed. If you call
@bclose() explicitly, the resource is removed, too.

.Back-ends:
- <<fbparam,Files (parametrized)>>
- <<fbfile,Regular files>>
- <<fbtemp,Temporary files>>
- <<fblim,File fragments>>
- <<fbmem,In-memory streams>>
- <<fbbuf,Buffers>>
- <<fbgrow,Growing buffers>>
- <<fbpool,Memory pools>>
- <<fbatomic,Atomic files>>

.Front-ends:
- <<ffbasic,Basic functions>>

.Wrappers:
- <<fwhex,Hexadecimal wrapper>>

.Other reading:
- <<internal,Internal structure>>
- <<bconfig,Configuring streams>>
- <<fbexc,Exceptions>>

ucw/fastbuf.h
-------------

!!ucw/fastbuf.h

ucw/fb-socket.h
---------------

Fastbufs on network sockets with timeouts.

!!ucw/fb-socket.h

ucw/ff-unicode.h
----------------

Reading and writing of unicode characters.

Invalid codes are replaced by `UNI_REPLACEMENT` when reading.

!!ucw/ff-unicode.h

ucw/ff-binary.h
---------------

!!ucw/ff-binary.h

ucw/fw-hex.h [[fwhex]]
----------------------

!!ucw/fw-hex.h

Exceptions [[fbexc]]
--------------------

All standard back-ends and front-ends raise exceptions on errors if the fastbuf
is tied to a resource pool by @fb_tie().
All such exceptions live in the `ucw.fb` subtree. The following exceptions are defined:

`ucw.fb.eof`:: Unexpected end of file (e.g., when the @FB_DIE_ON_EOF flag is set)
`ucw.fb.mmap`:: Memory mapping failed (e.g., the `mmap` syscall has failed)
`ucw.fb.open`:: Opening failed (file does not exist and similar problems)
`ucw.fb.read`:: Read error (e.g., the `read` syscall has failed or the stream is write-only)
`ucw.fb.seek`:: Seek error (e.g., file not seekable, or a seek behind EOF)
`ucw.fb.tmp`:: Creation of temporary file failed
`ucw.fb.toolong`:: Object (typically a line) is too long
`ucw.fb.write`:: Write error (e.g., the `write` syscall has failed or the stream is read-only)