- /* Start a new continuous block and prepare for writing (see mp_start()) */
-void *fbpool_end(struct fbpool *fb); /* Close the block and return its address (see mp_end()).
- The length can be determined with mp_size(mp, ptr). */
-
-/* FastO with atomic writes for multi-threaded programs */
+/**
+ * Close the block and return the address of its start (see <<mempool:mp_end()>>).
+ * The length can be determined by calling <<mempool:mp_size(mp, ptr)>>.
+ **/
+void *fbpool_end(struct fbpool *fb);
+
+/***
+ * === Atomic files for multi-threaded programs [[fbatomic]]
+ *
+ * This fastbuf backend is designed for cases when several threads
+ * of a single program append records to a common file and while the
+ * record can mix in an arbitrary way, the bytes inside a single
+ * record must remain uninterrupted.
+ *
+ * In case of files with fixed record size, we just allocate the
+ * buffer to hold a whole number of records and take advantage
+ * of the atomicity of the write() system call.
+ *
+ * With variable-sized records, we need another solution: when
+ * writing a record, we keep the fastbuf in a locked state, which
+ * prevents buffer flushing (and if the buffer becomes full, we extend it),
+ * and we wait for an explicit commit operation which write()s the buffer
+ * if the free space in the buffer falls below the expected maximum record
+ * length.
+ *
+ * Please note that initialization of the clones is not thread-safe,
+ * so you have to serialize it yourself.
+ ***/