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 is only active in ALPHA builds and optimized out in
   6 BETA and RELEASE builds.
   7
   8 HEAD++ Concepts;;
   9
  10 Resources are abstracted, NoBug has little knowledge about the semantics of a
  11 resource, it only keeps records of resources and the code using it and ensures
  12 basic constraints. Detailed usage checks of resource have to be done with other
  13 NoBug facilities.
  14
  15 Resources are identified by a arbitrary identifier which is just a
  16 pointer. Additionally a name, the type and the source locations which
  17 announced the resource are stored.
  18
  19 Code which wants to use a resource calls a enter macro with its own identifier
  20 and state, then might alter the state and finally a leave macro when finished
  21 with it.
  22
  23 When a resource is used one has to pass one of this states:
  24
  25   * NOBUG_RESOURCE_WAITING
  26       + For resources where acquisition could block (locks) you enter it with a
  27         WAITING state first and as soon you acquired it you change the state to one
  28         of the following.
  29   * NOBUG_RESOURCE_EXCLUSIVE
  30       + Acquired the resource exclusively. It must not be acquired
  31         again, not even from the same thread.
  32   * NOBUG_RESOURCE_RECURSIVE
  33       + The resource might be entered multiple times from the same
  34         thread with this state.
  35   * NOBUG_RESOURCE_SHARED
  36       + The resource might be entered multiple times from any thread
  37         with this state.
  38
  39 Possible state transitions:
  40
  41 ["graphviz", "resource-transistinons.png"]
  42 ---------------------------------------------------------------------
  43 strict digraph G
  44 {
  45         edge [fontname=Courier fontsize=10]
  46
  47         start [shape=ellipse]
  48
  49         node [shape=box]
  50
  51         start -> Waiting [label="ENTER()"]
  52         start -> Exclusive [label="ENTER()"]
  53         start -> Recursive [label="ENTER()"]
  54
  55         Waiting -> Exclusive [label="STATE()"]
  56         Waiting -> Recursive [label="STATE()"]
  57
  58         Recursive -> Recursive [label="ENTER()\nSTATE()"]
  59
  60         Waiting -> end [label="LEAVE()"]
  61         Exclusive -> end [label="LEAVE()"]
  62         Recursive -> end [label="LEAVE()"]
  63
  64         end [shape=ellipse]
  65 }
  66 ---------------------------------------------------------------------
  67
  68 HEAD== Notes;;
  69
  70 There are small race conditions in the time we
  71 announce/forget/enter/remove resources and doing the actual call to a
  72 resource. These race conditions affect the reporting exactness and are
  73 a design decision. When this poses a problem it will be fixed.
  74
  75 The Resource Tracker relies on that announce/forget and enter/leave
  76 are properly paired. The programmer should ensure that this is done
  77 right, else it will become unusable.
  78