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 abstracted, NoBug has little knowledge about the semantics of a
  14 resource, it only keeps records of resources and the code using it and ensures
  15 basic constraints. Detailed usage checks of resource have to be done with other
  16 NoBug facilities.
  17
  18 Resources are identified by a arbitrary identifier which is just a
  19 pointer. Additionally a name, the type and the source locations which
  20 announced the resource are stored.
  21
  22 Code which wants to use a resource calls a enter macro with its own identifier
  23 and state, then might alter the state and finally a leave macro when finished
  24 with it.
  25
  26 When a resource is used one has to pass one of this states:
  27
  28   * NOBUG_RESOURCE_WAITING
  29       + For resources where acquisition could block (locks) you enter it with a
  30         WAITING state first and as soon you acquired it you change the state to one
  31         of the following.
  32   * NOBUG_RESOURCE_EXCLUSIVE
  33       + Acquired the resource exclusively. It 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
  44 ["graphviz", "resource-transistinons.png"]
  45 ---------------------------------------------------------------------
  46 strict digraph G
  47 {
  48         edge [fontname=Courier fontsize=10]
  49
  50         start [shape=ellipse]
  51
  52         node [shape=box]
  53
  54         start -> Waiting [label="ENTER()"]
  55         start -> Exclusive [label="ENTER()"]
  56         start -> Recursive [label="ENTER()"]
  57
  58         Waiting -> Exclusive [label="STATE()"]
  59         Waiting -> Recursive [label="STATE()"]
  60
  61         Recursive -> Recursive [label="ENTER()\nSTATE()"]
  62
  63         Waiting -> end [label="LEAVE()"]
  64         Exclusive -> end [label="LEAVE()"]
  65         Recursive -> end [label="LEAVE()"]
  66
  67         end [shape=ellipse]
  68 }
  69 ---------------------------------------------------------------------
  70
  71 HEAD== Notes;;
  72
  73 There are small race conditions between logging and checking resource tracking
  74 and the actual call to the resource using function. This is a design decision
  75 there is no way to account for this exactly when the function call may block.
  76
  77 The Resource Tracker relies on proper announce/forget and enter/leave
  78 are properly pairing. The programmer should ensure that this is done
  79 right, otherwise the results are unpredictable.
  80