Documented memory resources.

1 files changed, 50 insertions, 0 deletions

diff --git a/lib/resource.sgml b/lib/resource.sgml
new file mode 100644
index 00000000..4123dd68
--- /dev/null
+++ b/lib/resource.sgml
@@ -0,0 +1,50 @@
+<!--
+	BIRD Programmer's Guide: Resources
+
+	(c) 2000 Martin Mares <mj@ucw.cz>
+-->
+
+<chapt>Resources
+
+<sect>Introduction
+
+<p>Most large software projects implemented in classical procedural
+programming languages usually end up with lots of code taking care
+of resource allocation and deallocation. Bugs in such code are often
+very difficult to find, because they cause only `resource leakage',
+that is keeping a lot of memory and other resources which nobody
+references to.
+
+<p>We've tried to solve this problem by employing a resource tracking
+system which keeps track of all the resources allocated by all the
+modules of BIRD, deallocates everything automatically when a module
+shuts down and it's is able to print out the list of resources and
+the corresponding modules they are allocated by.
+
+<p>Each allocated resource (and from now we'll speak about allocated
+resources only) is represented by a structure starting with a standard
+header (struct <struct/resource/) consisting of a list node (resources are
+often linked to various lists) and a pointer to <struct/resclass/ -- a resource
+class structure pointing to functions implementing generic resource
+operations (such as freeing of the resource) for the particular resource
+type.
+
+<p>There exist the following types of resources:
+
+<itemize>
+<item><it/Resource pools/ (<struct/pool/)
+<item><it/Memory blocks/
+<item><it/Linear memory pools/ (<struct/linpool/)
+<item><it/Slabs/ (<struct/slab/)
+<item><it/Sockets/ (<struct/socket/) 
+<item><it/Events/ (<struct/event/) 
+<!--
+ are there to keep track of deferred execution.
+	Since BIRD is single-threaded, it requires long lasting tasks to be split to smaller
+	parts, so that no module can monopolize the CPU. To split such a task, just create
+	an <struct/event/ resource, point it to the function you want to have called and call <func/ev_schedule()/
+	to ask the core to run the event when nothing more important will require attention.
+	The actual implementation is system dependent.
+-->
+<item><it/Timers/ (<struct/timer/) 
+</itemize>