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
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
!!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
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)
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,
!!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.
+- More exceptions
- Do we want to allow res_alloc() when no pool is active?
-- Structure of exception identifiers: rethink and document