]> git.buserror.net Git - polintos/scott/priv.git/blob - doc/orb/memory-management
Cause excessively large malloc()s to fail rather than assert.
[polintos/scott/priv.git] / 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.