ORB documentation updates.
authorScott Wood <scott@thor.buserror.net>
Sat, 31 May 2008 02:09:46 +0000 (21:09 -0500)
committerScott Wood <scott@thor.buserror.net>
Sat, 31 May 2008 02:09:46 +0000 (21:09 -0500)
Signed-off-by: Scott Wood <scott@thor.buserror.net>
doc/orb/ids
doc/orb/parameter-info-block
idl/objmgr.idl

index 0721a82b2a17cf65d2e1a1b09b8c780faabd514b..469303d9a34cddc3f79469b9ffe3e0ed3e90fae0 100644 (file)
@@ -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
index 9ad27eee0280c19c410ae193808fb372c6655d28..c4f176848cadb92e480df4ec2aaf912436350c7b 100644 (file)
@@ -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
index bf7d08a4e35a62df93091b82e44fd13fc4b129fa..764e055f6c1137319a9a1df421615fda67da6711 100644 (file)
@@ -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