/* System traps
 *
 * Traps are events delivered to a process or thread, similar to
 * POSIX signals.
 */

namespace Traps;

// The base Trap struct; all traps must derive from this.
struct Trap virtual {
	guid: "2B91FBD9-2878-11DA-98E8-00112431A05E";
};

// The kernel Process and Thread classes implement this interface. 
// When trap is invoked on a process, a trap is sent to all of the
// threads in the process.  When invoked on a thread, a trap is sent
// only to that thread. A trap can be sent to one arbitrary thread in
// a Process by getting a reference to a TrapDistributor class object
// for that Process.

interface Trappable {
	guid: "88661962-EAB6-11D9-9B1D-000A95BB581A";

	// Delivers a synchronous trap according to the rules of the
	// object on which this method was invoked.  "delivered" is false
	// if the trap was ignored, if this was a process's trappable and
	// there are no threads in the process, or if an error occured
	// that prevented delivery (though that case should generally be
	// handled with exceptions).  It is *not* false merely because the
	// trap was masked at the time.
	
	trap(Trap trap, bool delivered out);
};

// The kernel Process and Thread classes provide objects that 
// implement this interface. It is separate from Trappable for
// security reasons (plus, the distributor objects don't have their
// own masks).  If a trap is sent to a thread via its own Trappable,
// then only the thread's mask will be consulted.  If it is sent via
// a process's Trappable, either directly or through the distributor,
// the trap must pass both process and thread masks to be delivered.

interface TrapMaskTable {
	guid: "8D09635A-EAB6-11D9-A7EC-000A95BB581A";

	enum MaskState {
		Unmask,     // Accept this trap and its descendents, and
		            // deliver them immediately.  This is the
		            // default behavior.
		Mask,       // Accept this trap and its descendents, but don't
		            // deliver them until unmasked.
		Ignore,     // Ignore this trap and its descendents; the trap
		            // is discarded and will not be delivered even if
		            // the trap is later unmasked.
		DeleteEntry // Undo previous calls to set_mask for this trap,
		            // reverting ignored status to that of the trap's
		            // parent (or Ignore for the root Trap).  This is
		            // valid only for set_mask().
	};

	struct MaskEntry {
//		System.Objects.Struct trap;
		MaskState state;
	};

	// Sets the mask status for the trap in question, as well as its
	// children.  Previous calls to set_ignored on a descendent trap
	// will not be affected unless override is set to true (in which
	// case it's as if DeleteEntry were called on all descendents).
	
	set_mask(MaskEntry mask, bool override);
	
	// This returns the mask state for a given trap type, as well as
	// the specific trap type whose mask entry was used to determine
	// this (it will be either the given trap, or the nearest ancestor
	// with a mask entry).
	
//	get_mask(System.Objects.Struct trap, MaskEntry mask out);

	// Set the entire mask table as an unsorted linear list of entries.
	// If override is true, this replaces the existing mask table.
	// Otherwise, these entries are added to the list, overriding
	// only exact trap type matches.
	
	set_mask_table(MaskEntry[] entries, bool override);

	// Get the entire mask table as an unsorted linear list of entries.
	get_mask_table(MaskEntry[] entries out);
};

namespace Std;

// The ReduceMemoryUsage trap is delivered when the system is low on
// uncommitted virtual memory.  It is delivered to each process using
// uncommitted memory, in decreasing order of the amount of such memory,
// until enough memory is freed to accomodate the request.

struct ReduceMemoryUsage : Trap {
	guid: "40CBFDB6-2878-11DA-B80D-00112431A05E";

	// Amount of memory in bytes that are needed.  A process should
	// stop looking for memory to free once it has freed this amount
	// if it would save significant processing time, or if the memory
	// being freed is still useful as cached data.
	
	ulong mem_needed;
};