ucw/doc/fastbuf.txt

   1 Fastbufs
   2 ========
   3
   4 A *fastbuf* is a stream (or file) abstraction optimized for both speed
   5 and flexibility.
   6
   7 Fastbufs can represent many different kinds of objects: regular files, network
   8 sockets, file descriptors in general, or various memory buffers. These objects
   9 are handled by different fastbuf *back-ends.*
  10
  11 Once you have a fastbuf, you can access it by fuctions similar to those of
  12 `stdio.h`, or you can use a variety of fastbuf *front-ends* providing various
  13 formatted operations.
  14
  15 Please keep in mind that fastbufs do not allow arbitrary mixing of reads and
  16 writes on the same stream. If you need to mix them, you have to call @bflush()
  17 inbetween and remember that the file position reported by @btell() points after
  18 the flushed buffer, which is not necessarily the same as after the data you've
  19 really read.
  20
  21 Most fastbuf back-ends also participate in the libucw resource management system.
  22 If you have a resource pool active, newly created fastbufs are automatically tied
  23 to resources in the pool, so when the pool gets cleaned up, the fastbufs are
  24 freed, too. The bclose() function is still available and it removes the tie
  25 as needed.
  26
  27 .Back-ends:
  28 - <<fbparam,Files (parametrized)>>
  29 - <<fbfile,Regular files>>
  30 - <<fbtemp,Temporary files>>
  31 - <<fblim,File fragments>>
  32 - <<fbmem,In-memory streams>>
  33 - <<fbbuf,Buffers>>
  34 - <<fbgrow,Growing buffers>>
  35 - <<fbpool,Memory pools>>
  36 - <<fbatomic,Atomic files>>
  37
  38 .Front-ends:
  39 - <<ffbasic,Basic functions>>
  40
  41 .Other reading:
  42 - <<internal,Internal structure>>
  43 - <<bconfig,Configuring streams>>
  44
  45 ucw/fastbuf.h
  46 -------------
  47
  48 !!ucw/fastbuf.h
  49
  50 ucw/fb-socket.h
  51 ---------------
  52
  53 Fastbufs on network sockets with timeouts.
  54
  55 !!ucw/fb-socket.h
  56
  57 ucw/ff-unicode.h
  58 ----------------
  59
  60 Reading and writing of unicode characters.
  61
  62 Invalid codes are replaced by `UNI_REPLACEMENT` when reading.
  63
  64 !!ucw/ff-unicode.h
  65
  66 ucw/ff-binary.h
  67 ---------------
  68
  69 !!ucw/ff-binary.h