From 9cd5b143a255c39bf26b3accae3f15edda03ccc7 Mon Sep 17 00:00:00 2001 From: Scott Wood Date: Fri, 30 May 2008 21:09:46 -0500 Subject: [PATCH] ORB documentation updates. Signed-off-by: Scott Wood --- doc/orb/ids | 60 ++++++++++++++---------------------- doc/orb/parameter-info-block | 2 +- idl/objmgr.idl | 26 +++++++++++++--- 3 files changed, 45 insertions(+), 43 deletions(-) diff --git a/doc/orb/ids b/doc/orb/ids index 0721a82..469303d 100644 --- a/doc/orb/ids +++ b/doc/orb/ids @@ -1,46 +1,32 @@ IDs are used to identify a specific objects and methods to the ORB. Each -address space has its own object ID space, but method IDs are a separate ID -space that is shared by all users of an ORB. Each interface does *not* -form its own ID space for methods. Classes, interfaces, and struct types -are merely objects of specific classes, and thus share the object ID space. - -Object IDs -========== +address space has its own object ID space. Methods are identified by index +within an interface. Interfaces and struct types are merely objects that +implement specific introspection interfaces, and thus share the object ID +space. Applications interact with objects via pointers (or references, or whatever -else is appropriate for the language), not IDs. This includes structs -intended for marshalling to another address space. To deal with this, the -ORB accepts all object references in pointer form, rather than ID form. -For object references, the language mapping ensures that the ID can be -found from the pointer in a manner consistent with the platform ABI. -Typically, it is stored as some fixed offset of the first word of the -entity pointed to. Structs do not have IDs; see the "memory-management" -file for information on how they are marshalled across address spaces. +else is appropriate for the language), not IDs. Thus, the marshalling stubs +accept all object references in pointer form, rather than ID form. The +language mapping ensures that the ID can be found from the pointer in a +manner consistent with the platform ABI. Typically, it is stored as some +fixed offset of the first word of the entity pointed to. + +Objects are not assigned IDs until they are passed to the ORB. When +marshalling such an object, an ID is assigned from the local numberspace +(high-bit clear) by marshalling code, and the ID is added to the newobj +list, along with a SHA-1 hash of the list of interfaces associated with the +object (hereafter, the "interface hash"). The ID is stored into the object +for future use. When presenting the object to the destination address space, the ORB needs to convert the local object ID to the object ID in the server's ID space. If the object has not yet been used in that address space, there will be no -local ID (or pointer) associated with it. If this is the case, an object -stub will be created by the ORB. - -To maintain the ID->pointer mapping, the ORB will maintain a pointer object -for every local ID in an ID space that is not the "home" of the real -object. These objects, whose memory is chargeable to the address space -they were created for, contain the application address associated with the -ID, as well as a pointer to the real object. The pointer object may also -hold cached results of permission checks. - -For every real object, the ORB maintains a similar internal object, but -instead of a pointer to a real object, it contains all the information -needed for the ORB to carry out requests on the ID. - -Method IDs -========== +local ID (or pointer) associated with it. If this is the case, an ID in the +remote numberspace (high-bit set) will be created by the ORB, and the object +will be on the receiver's newobj list. -Each method has an ID which is global to the ORB, which is used when -specifying which method to invoke on a given object. A method will also -have an interface-local index "id", which can be used internally for things -such as indexing into a pointer-object's cached permission checks, but such -indices are not application-visible. The only pointer associated with a -method is its entry point, which is not visible to the client. +Marshalling code will maintain a wrapper object for every remote ID, as well +as an ID-to-pointer lookup table for both local and remote objects. +Each local and remote object contains two reference counts -- local and orb. +The local reference count \ No newline at end of file diff --git a/doc/orb/parameter-info-block b/doc/orb/parameter-info-block index 9ad27ee..c4f1768 100644 --- a/doc/orb/parameter-info-block +++ b/doc/orb/parameter-info-block @@ -26,7 +26,7 @@ Parameter Info Block (PIB) objlist_ptr pointer Pointer to the object list newobj_ptr pointer Pointer to the new object list. objlist_len 32-bit Length of the object list, in IDs - newobj_len 32-bit Length of the new object list, in hashes. + newobj_len 32-bit Length of the new object list, in entries. The object list is a special segment that contains object IDs rather than arbitrary data. Each object ID will be translated diff --git a/idl/objmgr.idl b/idl/objmgr.idl index bf7d08a..764e055 100644 --- a/idl/objmgr.idl +++ b/idl/objmgr.idl @@ -14,11 +14,15 @@ struct VStruct virtual { }; 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 uint ID; + + struct GUID { + ulong[2] data; + }; - typedef ulong ID; + struct IHash { + uint[5] data; + }; struct TypeDesc { enum BasicType { @@ -118,7 +122,7 @@ namespace Objects { interface IDSpace { guid: "06489629-9C25-4C14-9A5B-6C59639C87D6"; - new_object(Mem.AddrSpace aspace, ulong entry, ID obj out); + new_object(ID obj, IHash hash); // Release "num" references on the object. If exactly "num" // references remain, the object handle is closed and "gone" is @@ -132,6 +136,18 @@ namespace Objects { // a refcount of 1. release(ID obj, int num, bool gone out); + + // Delete an object regardless of the number of references. + // If the object is local, then all remote references will + // become dangling; any attempt to pass the handle to the + // ORB will result in an InvalidReference exception. + + revoke(ID obj); + + // Return the number of references to an object. + // This method is intended for debugging only. + + get_refs(ID obj, int num out); }; // This is a generic Factory interface; specific factories may -- 2.39.2