/* The Object Manager
 *
 * This is the kernel interface through which objects, interfaces, and
 * interfaces are opened, created and destroyed.  The instantiated objmgr
 * object is always id 1.
 */ 

interface Object {
	guid: "C227980E-EA8B-11D9-84F1-000A95BB581A";
};

struct VStruct virtual {
	guid: "E2E3AF5F-2858-11DA-9FBB-00112431A05E";
};

namespace Objects {
	// FIXME: make this a built-in ID type that fixes things
	// up when moving between systems.  It can be native word
	// sized, rather than always long.

	typedef ulong ID;

	struct TypeDesc {
		enum BasicType {
			Bool, Short, Int, Long,
			UShort, UInt, ULong,
			FShort, FLong, Octet, Enum, 
			Bitfield, Interface, Struct
		} type;
	
		ID id;            // ID of interface, struct, bitfield, or enum (or 0).
		ulong length;     // Type length: bits in bitfield, bytes in
		                  //              struct, max value of enum, or 0. 

		struct Array {
			// Inclusive lower and upper bounds of the array.  If the
			// array has no upper bound, upper should be -1.  If the
			// array has no lower bound, lower should be 0.  If this is
			// not an array, both should be 0.

			long lower, upper;
		} array;
	};
	
	struct ParamDesc {
		TypeDesc type;
	
		enum Dir {
			In, Out, InOut
		} dir;
	
		bitfield Attr:32 {
			copy:1,   /* If input argument references memory, a
			             copy will be made (possibly via copy-on-write)
			             before the method receives control.
			             If the parameter is inout, the changes (if any)
			             will be copied to the original memory area (or
			             the copy-on-write mapping will occur on return
			             from the method).  This is an implementation
			             attribute and is incompatible with shared. */
	
			shared:1, /* If input argument references memory, the
			             method may continue to access the memory
			             until it explicitly releases it.  The memory
			             region must remain valid until then, and all
			             changes to the memory area will be shared by
			             both the caller and the callee.  This is an
			             interface attribute and is incompatible with
			             copy.  The argument should be page aligned
			             and its size must be a multiple of the page
			             size; otherwise, the caller will have
			             access to data outside the region passed. */
		} attr;
	};
	
	struct MethodDesc {
		char[] name;
		ulong entry;      /* Address of method entry point */
		ParamDesc[] params;
	
		bitfield Flags:32 {
			async:1,       /* Method is invoked indirectly via message passing,
			                  and the caller does not wait for completion.  No
			                  out parameters may be used in such a method. */
			
			ordered:1,     /* Method requires strong ordering; all ordered methods
			                  from the same thread will be delivered in order, and
			                  the next such method will not be delivered until
			                  the recipient of the previous invocation message
			                  acknowledges it.  This flag is only valid on async
			                  methods, as synchronous methods are inherently
			                  ordered. 
			                  
			                  An alternative is to invoke methods through
			                  a serialization object, which allows finer
			                  control over the level of serialization.
			                  This flag may go away in favor of always
			                  using explicit serialization objects when
			                  needed. */
		} flags;
	};
	
	struct ClassDesc {
		ulong[] super;		/* superinterface(es) */
		MethodDesc[] methods;
		ulong instantiate, subinterface, remove;	/* access tokens */
	};
	
	struct DatumDesc {
		char[] name;
		TypeDesc type;
	};
	
	struct StructDesc {
		DatumDesc[] data;
	};

	interface IDSpace {
		guid: "06489629-9C25-4C14-9A5B-6C59639C87D6";

		new_object(Mem.AddrSpace aspace, ulong entry, ID obj out);
		
		// Release "num" references on the object.  If exactly "num"
		// references remain, the object handle is closed and "gone" is
		// true.  If more references remain, the handle is not closed and
		// "gone" is false.  If fewer references than "num" are present
		// when called, no references are released, and RefCountException
		// is thrown.
		//
		// A handle's refcount is incremented whenever a reference is
		// received via IPC.  Objects created with new_object start with
		// a refcount of 1.
		
		release(ID obj, int num, bool gone out);
	};
	
	// This is a generic Factory interface; specific factories may
	// (but do not need to) implement a more specific interface that
	// guarantees that the generated object will comply with some
	// particular interface.
	
	interface Factory {
		guid: "9C084DD0-5D69-11DA-BD5A-000A95BB581A";
		create(Object obj out);
	};
}