X-Git-Url: http://mj.ucw.cz/gitweb/?a=blobdiff_plain;f=ucw%2Fdoc%2Ffastbuf.txt;h=86ab55d923dba0b55026c31489b4e050d4e9dfc9;hb=a45646a634b71708f5bc4277868c60e80daaa84c;hp=71e9dc07dd1418cc9ef123cf29562f30d593acbe;hpb=01b1c8a44e698ba72a0e24c6c02a3662c3ba9fa2;p=libucw.git

diff --git a/ucw/doc/fastbuf.txt b/ucw/doc/fastbuf.txt
index 71e9dc07..86ab55d9 100644
--- a/ucw/doc/fastbuf.txt
+++ b/ucw/doc/fastbuf.txt
@@ -1,14 +1,69 @@
 Fastbufs
 ========
 
-Fastbufs are stream and file abstractions. They work with normal
-files, network sockets, memory buffers or just any file descriptor. It
-should be easy to implement other types by providing functions to
-refill and read the buffer.
+A *fastbuf* is a stream (or file) abstraction optimized for both speed
+and flexibility.
 
-Apart from abstraction, they are very fast.
+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 fuctions similar to those of
+`stdio.h`, or you can use a variety of fastbuf *front-ends* providing various
+formatted operations.
+
+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.
+
+Most fastbuf back-ends also participate in the libucw resource management system.
+If you have a resource pool active, newly created fastbufs are automatically tied
+to resources in the pool, so when the pool gets cleaned up, the fastbufs are
+freed, too. The bclose() function is still available and it removes the tie
+as needed.
+
+.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>>
+
+.Other reading:
+- <<internal,Internal structure>>
+- <<bconfig,Configuring streams>>
 
 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