You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
97 lines
2.9 KiB
97 lines
2.9 KiB
2 months ago
|
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)
|