doc/orb/memory-management

   1 1. Method Parameters
   2 ====================
   3
   4 1.1 Overview
   5 ============
   6
   7 This document defines the lifetime and writeability of memory passed by
   8 reference as a parameter under various circumstances (in or out, sync or
   9 async).  The implementation of the semantics will be different for local
  10 and remote methods, and not all restrcitions are enforced as strictly for
  11 local methods, but the semantics when the rules are followed must be the
  12 same for both.
  13
  14 1.2 Definitions
  15 ===============
  16
  17 implementation attribute: An attribute that is defined only for a specific
  18 server object, and affects only the server stubs.  It can be changed
  19 without breaking client compatibility.
  20
  21 interface attribute: An attribute that is defined as a part of an IDL
  22 interface, and cannot be changed without breaking compatibility.
  23
  24 local: The method being called exists in the caller's address space, and
  25 thus no marshalling need occur.
  26
  27 remote: The method being called exists in an address space other than the
  28 caller's.  All data must be marshalled and passed through some form of
  29 IPC.
  30
  31 1.3 In Parameters
  32 =================
  33
  34 Built-in datatypes, bitfields, enums, and inline structs and arrays are
  35 passed directly by value (or, depending on the ABI, a reference valid
  36 until the end of the method for out parameters), and thus do not require
  37 memory management for local calls.  For remote calls, data passed by
  38 value is treated as a single non-inline struct for synchronous methods,
  39 and as an inline struct (copied at invocation time, and freed when the
  40 message is removed from the queue by the ORB) for async methods.
  41
  42 Object references are reference counted both at the ORB and process
  43 level, and are unique in that the client data structures are read-only
  44 and uncopyable (because a unique object needs a unique address) within an
  45 address space; most of this section does not apply to them.
  46
  47 That leaves non-inline structs and arrays.  These are  passed as a simple
  48 pointer (plus a length field in the case of arrays), with the method
  49 copying anything it wants to change and/or keep beyond the end of the
  50 method.  For async methods, the caller needs to avoid modifying referenced
  51 memory until it knows the method has been executed (in the remote case, it
  52 only matters until the ORB has COWed or copied the memory, but client code
  53 should not depend on this, or it will not work with an local server).
  54 There are no allocator or alignment restrictions on the memory being
  55 passed (though page alignment and overmap can improve performance when
  56 sending large buffers).
  57
  58 If the server wants to keep the data past the end of the method, or if it
  59 wants to modify the data, it must call a duplicate() function to copy the
  60 data, map it copy-on-write.  Struct duplications will need to do a deep
  61 copy without being confused by reference loops (possibly by using a hash
  62 table or other associative array to identify reference loops if IDLC
  63 determines that they are possible with that particular type of struct).
  64
  65 To avoid a double-copy, remote methods may want to merely ask the ORB to
  66 give it full, permanent access (via COW if not already copied) to the
  67 memory.  This may be hard to implement, though, as it requires the server
  68 to know that the data came from an remote implementation, and be able to
  69 modify the set of pages that the ORB reclaims at the end of the method
  70 call.  This may not provide a significant benefit over simply creating a
  71 new copy-on-write mapping.
  72
  73 In remote calls, the caller is charged with the temporary allocations made
  74 by the ORB in the callee's address space.
  75
  76 1.3.1 Copy (interface)
  77 ======================
  78
  79 The "copy" interface attribute may be used to achieve the effect of
  80 calling duplicate() in the server.  For local calls, this simply results
  81 in a call to duplicate() in the client stubs.  For remote calls, the
  82 copied data segments are marked with the Copy flag, which are read/write
  83 (using copy-on-write) and not freed at the end of the method.  These pages
  84 are charged to the callee, and must be freed using the callee's ORB memory
  85 manager.  The callee should be able to specify how much data it is willing
  86 to have copied to a given object.
  87
  88 The "copy" interface attribute may not be used on "out" parameters, and
  89 for "inout" parameters only applies to the "in" phase.  Do not confuse
  90 this with the implementation "copy" attribute used on "out" parameters.
  91
  92 1.4 Out parameters
  93 ==================
  94
  95 When a non-inline struct or array is being returned via an out or inout
  96 parameter, there is no end of method on which to base reference lifetime.
  97 As such, the ownership of such data is transferred to the ORB memory
  98 manager in the caller's address space.  For remote calls, the caller
  99 should be able to specify a limit on how much memory it is willing to
 100 receive from the callee.
 101
 102 Inline "out" parameters are returned into a buffer provided by the caller.
 103 All value types are implicitly inline.
 104
 105 1.4.1 Copy (implementation)
 106 ===========================
 107
 108 If the "copy" implementation attribute is specified on the out parameter,
 109 then the buffer the caller receives will be newly allocated, and the
 110 buffer provided by the callee remains the callee's.  In this case, there
 111 are no allocator or alignment restrictions on the callee's buffer.
 112
 113 If the "copy" attribute is not specified, then the buffer provided by the
 114 callee must be under the control of the ORB memory manager, and it must
 115 begin and end on page boundaries.  When returning from a remote call, the
 116 pages will be unmapped from the callee and mapped into the caller.
 117
 118 The "copy" implementation attribute may not be used on "in" parameters,
 119 and for "inout" parameters only applies to the "out" phase.  Do not
 120 confuse this with the interface "copy" attribute used on "in" parameters.
 121
 122 1.5 Inline
 123 ==========
 124
 125 When used as a parameter attribute (either explicitly or as part of the
 126 type definition), "inline" specifies that the struct or array will be
 127 passed directly as a value parameter.  A NULL reference cannot be passed,
 128 and for out parameters, the method cannot return a reference to an
 129 existing struct or array, but instead must fill in the reference given.
 130
 131 An inline array cannot be of variable length, and may be treated
 132 differently from other arrays in the language binding (e.g. in C++, inline
 133 arrays are bare language arrays, and do not use the Array or MutableArray
 134 wrappers).
 135
 136 The "inline" attribute can also be used on members of a struct, to
 137 indicate that the member is embedded directly in the outer struct, rather
 138 than linked with a pointer.
 139
 140 "Inline" is an interface attribute.
 141
 142 1.3 Asynchronous methods
 143 ========================
 144
 145 Most of the semantics are the same for asynchronous methods; however, the
 146 points at which the method begins and ends are less clear.  As far as the
 147 ORB is concerned, an async method begins when it processes the message.
 148 When invoking an async method, there should be a mechanism to get a handle
 149 to track the progress of the invocation.  This can be used by the caller
 150 to try to cancel the method on a timeout, which can only be done if the
 151 message has not yet been accepted by the recipient.  Once the message has
 152 been accepted, in the local, non-"copy" case, the caller must not
 153 touch the data after this point until it receives a message from the
 154 callee that it is finished.  In the remote case, if a caller loses
 155 patience with the callee, it can free the memory (thus making it exist
 156 only in the callee's address space, non-shared).
 157
 158 1.5 Exceptions
 159 ==============
 160
 161 Exceptions are thrown as copied out parameters.  This will often mean
 162 unnecessary copies at local IDL method boundaries, but exceptions should
 163 be small and infrequently thrown, and usually not managed by the ORB
 164 memory manager except across method boundaries.
 165
 166 2. The ORB Memory Manager (ORBMM)
 167 =================================
 168
 169 The ORB memory manager keeps track of memory that is allocated in the
 170 process of calling or returning from a method.  This happens with "copy"
 171 in parameters, and all non-inline out parameters.
 172
 173 2.1 Methods
 174 ===========
 175
 176 Each language binding shall provide a mechanism by which code may call the
 177 following functions on a given type of array or struct.  The prototypes
 178 are for C++; other language bindings express these methods in whatever
 179 form is most appropriate.  In C++, the ORB memory manager is at
 180 System::RunTime::orbmm, which is a pointer to an instance of
 181 System::RunTime::ORBMM.
 182
 183 2.1.1 alloc
 184 ===========
 185
 186 void *ORBMM::alloc(size_t size, int refs = 1);
 187
 188 Allocate the memory required for the given type, array length, and
 189 inital refcount.
 190
 191 Alternate forms:
 192 Type *obj = new(orbmm) Type;
 193 Type *obj = new(orbmm) Type[];
 194 Type *obj = new(orbmm, refs) Type;
 195 Type *obj = new(orbmm, refs) Type[];
 196
 197 2.1.2 retain
 198 ============
 199
 200 void ORBMM::retain(void *ptr, int refs = 1);
 201
 202 Add the specified number of references to the ORBMM object.  "ptr" can
 203 be anywhere inside the object; it does not have to point to the
 204 beginning of the object.
 205
 206 2.1.3 release
 207 =============
 208
 209 void ORBMM::free(void *ptr, int refs = 1);
 210
 211 Alternate forms:
 212 delete(orbmm) Type;
 213 delete(orbmm) Type[];
 214 delete(orbmm, refs) Type;
 215 delete(orbmm, refs) Type[];
 216
 217 Release the specified number of references to the ORBMM object. If
 218 the refcount falls to zero, the memory will be unmapped.  If the
 219 refcount goes below zero, an exception may be thrown.  "ptr" can be
 220 anywhere inside the object; it does not have to point to the
 221 beginning of the object.
 222
 223 2.1.3 add_region
 224 ================
 225
 226 void ORBMM::add_region(System::Mem::Region region, bool unmap_orig,
 227                        int refs = 1);
 228
 229 The add_region method places a non-ORBMM controlled region under ORBMM
 230 control.  This can be used to return data that was not allocated using
 231 ORBMM (such as static data or non-anonymous mappings), without having
 232 to always do so (as the "copy" attribute would require).  It is also
 233 used internally by IDL stubs.
 234
 235 The entire region will be one ORBMM object, and will be freed all at
 236 once when the refcount goes to zero.  When it is freed, the region
 237 will cease to be under ORBMM control.  The original region will only
 238 be unmapped if unmap_orig is true.