Trans: Document which modules have to be resourcified

[libucw.git] / ucw / doc / trans.txt

diff --git a/ucw/doc/trans.txt b/ucw/doc/trans.txt
index d2c10df31ba6b2753075000edaddfb34eb9e92f1..3ebf7543e964d33f79edc1f4de91ea477eea318d 100644 (file)
--- a/ucw/doc/trans.txt
+++ b/ucw/doc/trans.txt
@@ -10,8 +10,13 @@ exceptions similar to those in higher-level languages. An exception
 then rolls back the transaction, freeing all temporary resources allocated
 within the transaction.
 
-Resource pools: ucw/respool.h
------------------------------
+- <<respools,Resource pools>>
+- <<trans,Transactions>>
+- <<exc,Exceptions>>
+- <<excnames,Exception names>>
+
+Resource pools: ucw/respool.h [[respools]]
+------------------------------------------
 
 A resource pool contains a stack of resources. When a new resource
 is created, it is pushed onto the stack. When freeing the pool, the
@@ -22,6 +27,14 @@ A resource can be also freed separately (which unlinks it from the pool),
 or *detached* from the pool (which keeps the real resource, but forgets
 its meta-data, so the resource is no longer tracked).
 
+In many cases, a combination of both methods is needed: some resources
+are marked as temporary, while some others are permanent. When the
+an operation is completed successfully (and @rp_commit() is called),
+all temporary resources are freed and the permanent ones detached.
+When the operation fails, @rp_delete() deletes all resources. By default,
+all resources are created as temporary. You can make a resource permanent
+by calling @res_permanent(), or change the default in `resource->default_res_flags`.
+
 For each thread, LibUCW remembers the currently active resource pool.
 One pool can be used for at most one thread at a time. All functions
 which create resources do so in the active pool. All other functions
@@ -29,8 +42,8 @@ operating on resources work on both active and in-active pools.
 
 !!ucw/respool.h
 
-Transactions: ucw/trans.h
--------------------------
+Transactions: ucw/trans.h [[trans]]
+-----------------------------------
 
 Upon the resource pools, a transactional mechanism is built. A transaction
 consists of a piece of code and a resource pool for temporary objects created
@@ -41,7 +54,8 @@ When a transaction ends, the pool is destroyed and the previous active
 pool is popped off the transaction stack. The fate of the resources
 inside the pool depends on the operation used to end the transaction:
 
-* *commit* -- all resources are detached from the pool
+* *commit* -- permanent resources are detached from the pool, temporary
+  resources are freed
 * *rollback* -- all resources are freed
 * *fold* -- instead of destroying the pool, it is added as a subpool
   to the parent transaction (which must exist)
@@ -63,7 +77,7 @@ the parent transaction's pool.
 and the transaction logic uses @mp_push() and @mp_pop() to keep a stack
 of per-transaction data.)
 
-=== Exceptions ===
+=== Exceptions [[exc]] ===
 
 Transactions are commonly used together with exceptions (which are similar
 to how exceptions work in other languages, but they differ in subtle details,
@@ -120,10 +134,23 @@ are of course destroyed during the `longjmp()`.
 
 !!ucw/trans.h
 
+== Exception names [[excnames]] ==
+
+Exception identifiers form a hierarchy. Each identifier consists of dot-separated
+components with the most general component at the beginning.
+
+All exceptions raised by LibUCW reside in the `ucw` subtree. So far, the
+following exception types are defined:
+
+`ucw.fb`:: <<fastbuf:fbexc,Fastbufs>>
+
 == FIXME's ==
 
-- Interaction between exceptions, pools and other libucw modules.
 - Unit tests
-- Resourcification of more libucw objects.
-- Do we want to allow res_alloc() when no pool is active?
-- Structure of exception identifiers: rethink and document
+- Resourcification of more libucw objects:
+       * bigalloc
+       * eltpool
+       * gary
+       * mainloop
+       * mempool
+- More exceptions