doc/resourcetracking.txt

   1 HEAD- Resource Tracking;;
   2
   3 With little effort, NoBug can watch all kinds of resources a program uses. This
   4 becomes useful for resources which are distributed over a multithreaded
   5 program. Resource tracking includes logging actions on resource and checking
   6 locking policies over acquired resources. Resource logging is active in ALPHA
   7 and BETA builds when NOBUG_RESOURCE_LOGGING is defined to 1 (the default).
   8 The resource tracker which supervises locking policies is only enabled in
   9 ALPHA builds.
  10
  11 HEAD++ Concepts;;
  12
  13 Resources are an abstract entity for NoBug, which has little knowledge about the
  14 kinds of resources; it only keeps records of resources and the code using
  15 these resources and ensures basic constraints. More detailed checks on resource
  16 usage have to be done with other NoBug facilities.
  17
  18 Resources are identified by an arbitrary identifier which is just a
  19 pointer. Additionally a name, the type and the source locations which
  20 registered the resource are stored.
  21
  22 Code which requiring to use a resource, calls an 'ENTER' macro, supplying
  23 an identifier and state. The state can be altered. Thereafter a 'LEAVE' macro is
  24 used when the the code is finished with the resources.
  25
  26 When a resource is used, one has to pass one of these states:
  27
  28   `NOBUG_RESOURCE_WAITING`::
  29         For resources which might need to be blocked (locks),  enter with a
  30         WAITING state first, as soon at the resource is acquired, change the
  31         state to one of the following.
  32   `NOBUG_RESOURCE_EXCLUSIVE`::
  33         Acquired the resource exclusively. The resource must not be acquired
  34         again, not even from the same thread.
  35   `NOBUG_RESOURCE_RECURSIVE`::
  36         The resource might be entered multiple times from the same
  37         thread with this state.
  38   `NOBUG_RESOURCE_SHARED`::
  39         The resource might be entered multiple times from any thread
  40         with this state.
  41
  42 //.Possible state transitions
  43 ["graphviz", "resource-transitions.eps"]
  44 ---------------------------------------------------------------------
  45 strict digraph G
  46 {
  47         edge [fontname=Courier fontsize=10]
  48
  49         start [shape=ellipse]
  50
  51         node [shape=box]
  52
  53         start -> Waiting [label="ENTER()"]
  54         start -> Exclusive [label="ENTER()"]
  55         start -> Recursive [label="ENTER()"]
  56
  57         Waiting -> Exclusive [label="STATE()"]
  58         Waiting -> Recursive [label="STATE()"]
  59
  60         Recursive -> Recursive [label="ENTER()\nSTATE()"]
  61
  62         Waiting -> end [label="LEAVE()"]
  63         Exclusive -> end [label="LEAVE()"]
  64         Recursive -> end [label="LEAVE()"]
  65
  66         end [shape=ellipse]
  67 }
  68 ---------------------------------------------------------------------
  69
  70 HEAD== Notes;;
  71
  72 The Resource Tracker relies on proper announce/forget and enter/leave
  73 are properly paired. The programmer should ensure that this is correctly
  74 done, otherwise the results are unpredictable.
  75