idl/traps.idl

   1 /* System traps
   2  *
   3  * Traps are events delivered to a process or thread, similar to
   4  * POSIX signals.
   5  */
   6
   7 namespace Traps;
   8
   9 // The base Trap struct; all traps must derive from this.
  10 struct Trap virtual {
  11         guid: "2B91FBD9-2878-11DA-98E8-00112431A05E";
  12 };
  13
  14 // The kernel Process and Thread classes implement this interface.
  15 // When trap is invoked on a process, a trap is sent to all of the
  16 // threads in the process.  When invoked on a thread, a trap is sent
  17 // only to that thread. A trap can be sent to one arbitrary thread in
  18 // a Process by getting a reference to a TrapDistributor class object
  19 // for that Process.
  20
  21 interface Trappable {
  22         guid: "88661962-EAB6-11D9-9B1D-000A95BB581A";
  23
  24         // Delivers a synchronous trap according to the rules of the
  25         // object on which this method was invoked.  "delivered" is false
  26         // if the trap was ignored, if this was a process's trappable and
  27         // there are no threads in the process, or if an error occured
  28         // that prevented delivery (though that case should generally be
  29         // handled with exceptions).  It is *not* false merely because the
  30         // trap was masked at the time.
  31
  32         trap(Trap trap, bool delivered out);
  33 };
  34
  35 // The kernel Process and Thread classes provide objects that
  36 // implement this interface. It is separate from Trappable for
  37 // security reasons (plus, the distributor objects don't have their
  38 // own masks).  If a trap is sent to a thread via its own Trappable,
  39 // then only the thread's mask will be consulted.  If it is sent via
  40 // a process's Trappable, either directly or through the distributor,
  41 // the trap must pass both process and thread masks to be delivered.
  42
  43 interface TrapMaskTable {
  44         guid: "8D09635A-EAB6-11D9-A7EC-000A95BB581A";
  45
  46         enum MaskState {
  47                 Unmask,     // Accept this trap and its descendents, and
  48                             // deliver them immediately.  This is the
  49                             // default behavior.
  50                 Mask,       // Accept this trap and its descendents, but don't
  51                             // deliver them until unmasked.
  52                 Ignore,     // Ignore this trap and its descendents; the trap
  53                             // is discarded and will not be delivered even if
  54                             // the trap is later unmasked.
  55                 DeleteEntry // Undo previous calls to set_mask for this trap,
  56                             // reverting ignored status to that of the trap's
  57                             // parent (or Ignore for the root Trap).  This is
  58                             // valid only for set_mask().
  59         };
  60
  61         struct MaskEntry {
  62                 System.Objects.Struct trap;
  63                 MaskState state;
  64         };
  65
  66         // Sets the mask status for the trap in question, as well as its
  67         // children.  Previous calls to set_ignored on a descendent trap
  68         // will not be affected unless override is set to true (in which
  69         // case it's as if DeleteEntry were called on all descendents).
  70
  71         set_mask(MaskEntry mask, bool override);
  72
  73         // This returns the mask state for a given trap type, as well as
  74         // the specific trap type whose mask entry was used to determine
  75         // this (it will be either the given trap, or the nearest ancestor
  76         // with a mask entry).
  77
  78         get_mask(System.Objects.Struct trap, MaskEntry mask out);
  79
  80         // Set the entire mask table as an unsorted linear list of entries.
  81         // If override is true, this replaces the existing mask table.
  82         // Otherwise, these entries are added to the list, overriding
  83         // only exact trap type matches.
  84
  85         set_mask_table(MaskEntry[] entries, bool override);
  86
  87         // Get the entire mask table as an unsorted linear list of entries.
  88         get_mask_table(MaskEntry[] entries out);
  89 };
  90
  91 namespace Std;
  92
  93 // The ReduceMemoryUsage trap is delivered when the system is low on
  94 // uncommitted virtual memory.  It is delivered to each process using
  95 // uncommitted memory, in decreasing order of the amount of such memory,
  96 // until enough memory is freed to accomodate the request.
  97
  98 struct ReduceMemoryUsage : Trap {
  99         guid: "40CBFDB6-2878-11DA-B80D-00112431A05E";
 100
 101         // Amount of memory in bytes that are needed.  A process should
 102         // stop looking for memory to free once it has freed this amount
 103         // if it would save significant processing time, or if the memory
 104         // being freed is still useful as cached data.
 105
 106         ulong mem_needed;
 107 };