summaryrefslogtreecommitdiff
path: root/TAO/tao/Sequence.h
blob: 023e41564811080f2b6a15d1af662978de0ac486 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
/* -*- C++ -*- */
// $Id$

// ============================================================================
//
// = LIBRARY
//    TAO
//
// = FILENAME
//    sequence.h
//
// = AUTHOR
//
//    Carlos O'Ryan and Aniruddha Gokhale
//
// ============================================================================

#if !defined (TAO_SEQUENCE_H)
#  define TAO_SEQUENCE_H

class CORBA_Object;
class CORBA_Environment;

class TAO_Export TAO_Base_Sequence
{
  // = TITLE
  //   Base class for TAO sequences.
  //
  // = DESCRIPTION
  //   This class provides a common interface for all IDL sequences,
  //   hence the interpreted marshal engine can manipulate them in a
  //   type safe manner.
public:
  friend class TAO_Marshal_Sequence;
  // We give access to TAO_Marshal_Sequence, this allows a safe yet
  // small footprint implementation of the marshal engine.

  virtual ~TAO_Base_Sequence (void);
  // destructor.

  CORBA::ULong maximum (void) const;
  // return the maximum length of the sequence

  virtual void _allocate_buffer (CORBA::ULong length) = 0;
  // Ensure that the buffer contains space for at least <length>
  // elements.  The constructor must be called for any new elements,
  // the old ones (if any) must be copied into the buffer using
  // operator= and then their destructors must be called.
  // Finally the old buffer must be released.

  virtual void _deallocate_buffer (void) = 0;
  // Must deallocate the buffer and then set it to zero.

  virtual void _shrink_buffer (CORBA::ULong new_length,
                               CORBA::ULong old_length);
  // Some sequences (of objects and strings) require some cleanup if
  // the sequence is shrunk. The spec requires the destructor to
  // release the objects only from position <0> to <length-1>; so
  // shrink and then delete could result in a memory leak.

  virtual void _downcast (void* target,
			  CORBA_Object* src,
			  CORBA_Environment &_env = CORBA_Environment::default_environment ());
  // Used for sequences of objects to downcast a recently demarshalled
  // object reference into the right type.

  virtual CORBA_Object* _upcast (void* src) const;
  // Used for sequences of object to convert from the derived type
  // into the Object class.

protected:
  TAO_Base_Sequence (void);
  // Default constructor.

  TAO_Base_Sequence (CORBA::ULong maximum,
                     CORBA::ULong length,
                     void *buffer,
                     CORBA::Boolean release = 0);
  // Constructor with control of ownership.

  TAO_Base_Sequence (CORBA::ULong maximum,
                     void *buffer);
  // Assume ownership and set length to 0.

  TAO_Base_Sequence (const TAO_Base_Sequence &rhs);
  TAO_Base_Sequence &operator= (const TAO_Base_Sequence &rhs);
  // Copy constructor and assignment operator are protected, the
  // derived classes must provided the right semantics for the buffer
  // copy, only the static fields are actually copy.

  // = orbos/98-01-11 proposed extensions.
  CORBA::Boolean release (void) const;
  // Returns the state of the sequence release flag.

protected:
  CORBA::ULong maximum_;
  // The maximum number of elements the buffer can contain.

  CORBA::ULong length_;
  // The current number of elements in the buffer.

  void *buffer_;
  // The buffer with all the elements, casting must be done in derived
  // classes.

  CORBA::Boolean release_;
  // If true then the sequence should release the buffer when it is
  // destroyed.
};

// ****************************************************************

class TAO_Export TAO_Unbounded_Base_Sequence : public TAO_Base_Sequence
{
  // = TITLE
  //   Base class for all bounded sequences.
  //
  // = DESCRIPTION
  //   This class implements part of the funcionality common to all
  //   bounded sequences, using this intermediate class instead of
  //   virtual methods on TAO_Base_Sequence give us a slight
  //   improvement of performance, but also reduces the amount of
  //   generated code in the templates.
public:
  void length (CORBA::ULong length);
  // = SPEC {16.11.2}
  // For an unbounded sequence, setting the length to a larger value
  // than the current length may reallocate the sequence
  // data. Reallocation is conceptually equivalent to creating a new
  // sequence of the desired new length, copying the old sequence
  // elements zero through length into the new sequence, and then
  // assigning the old sequence to be the same as the new sequence.

  CORBA::ULong length (void) const;
  // return the current length, it cannot go into the base class due
  // to the C++ name lookup rules (if you don't know what I'm talking
  // about, then try moving it there).

protected:
  TAO_Unbounded_Base_Sequence (void);
  // Default constructor.

  virtual ~TAO_Unbounded_Base_Sequence (void);
  // destructor.

  TAO_Unbounded_Base_Sequence (CORBA::ULong maximum,
                               CORBA::ULong length,
                               void *buffer,
                               CORBA::Boolean release = 0);
  // Constructor with control of ownership.

  TAO_Unbounded_Base_Sequence (CORBA::ULong maximum,
                               void *buffer);
  // Assume ownership and set length to 0.
};

// ****************************************************************

class TAO_Export TAO_Bounded_Base_Sequence : public TAO_Base_Sequence
{
  // = TITLE
  //   Base class for all bounded sequences.
  //
  // = DESCRIPTION
  //   This class implements part of the funcionality common to all
  //   bounded sequences, using this intermediate class instead of
  //   virtual methods on TAO_Base_Sequence give us a slight
  //   improvement of performance, but also reduces the amount of
  //   generated code in the templates.
public:
  void length (CORBA::ULong length);
  // set the length, for this sequences this call is ignored if the
  // new length is greater that the maximum.

  CORBA::ULong length (void) const;
  // return the current length, it cannot go into the base class due
  // to the C++ name lookup rules (if you don't know what I'm talking
  // about, then try moving it there).

protected:
  TAO_Bounded_Base_Sequence (void);
  // Default constructor.

  virtual ~TAO_Bounded_Base_Sequence (void);
  // destructor.

  TAO_Bounded_Base_Sequence (CORBA::ULong maximum,
                             CORBA::ULong length,
                             void *buffer,
                             CORBA::Boolean release = 0);
  // Constructor with control of ownership.

  TAO_Bounded_Base_Sequence (CORBA::ULong maximum,
                             void *buffer);
  // Assume ownership and set length to 0.
};

/****************************************************************/

class TAO_Export TAO_String_Manager
{
  // = TITLE
  //   Manager for strings.
  //
  // = DESCRIPTION
  //   Similar to the mapping for sequences of objects (and other
  //   pseudo objects) the mapping for sequences of strings requires
  //   an auxiliar class or <Manager> to handle the allocation and
  //   deallocation of the string.  The main difference with respect
  //   to String_var classes is that automatic release is not
  //   controlled on a per-item basis, but for the sequence as a
  //   whole.  The difference wrt Object_Manager is that strings are
  //   duplicated using CORBA::string_copy() as opposed to
  //   T::_duplicate(), and released using CORBA::string_free()
  //   instead of CORBA::release()
  //
  //   This class implements the generic string manager and is used to
  //   instantiate the proper sequence types.
  //
public:
  friend class TAO_Unbounded_String_Sequence;

  // @@ Giving friendship to a template is not implemented on several
  // compilers:
  // friend template<CORBA::ULong MAX>
  //   class TAO_Bounded_String_Sequence<TAO_String_Manager,MAX>;

  TAO_String_Manager (const TAO_String_Manager &);
  // copy constructor

  TAO_String_Manager (char **buffer, CORBA::Boolean release);
  // constructor from address of an element

  ~TAO_String_Manager (void);
  // destructor

  TAO_String_Manager &operator= (const TAO_String_Manager&);
  // assignment from another managed type

  TAO_String_Manager &operator= (const char *);
  // assignment from a constant char*

  operator const char*() const;
  // cast  (read-only)

  const char *in (void) const;
  // for in parameter.
  
  char *&inout (void);
  // for inout parameter.
  
  char *&out (void);
  // for out parameter.
  
  char *_retn (void);
  // for string of return type.

private:
  char **ptr_;
  // Address of string element from the parent's buffer.

  CORBA::Boolean release_;
  // control memory managment semantics.
};

// ****************************************************************

class TAO_Export TAO_Unbounded_String_Sequence : public TAO_Unbounded_Base_Sequence
{
  // =TITLE
  //  Unbounded sequence of strings.
  //
  // =DESCRIPTION
  //  IDL sequences of strings must automatically duplicate and
  //  release their members based on some global <release> flag.

  // = SPEC
  // 16.8 Mapping for Structured Types
  // The mapping for struct, union, and sequence (but not array) is a
  // C++ struct or class with a default constructor, a copy
  // constructor, an assignment operator, and a destructor.
  //
public:
  // = Operations for the Unbounded_ObjectSequence

  TAO_Unbounded_String_Sequence (void);
  // {orbos/97-05-15:16.8}
  // The default constructor initializes object reference members to
  // appropriately typed nil object references and string members to
  // NULL; all other members are initialized via their default
  // constructors.
  //
  // {orbos/97-05-15:16.11}
  // For both bounded and unbounded sequences, the default constructor
  // (as shown in the example above) sets the sequence length equal to
  // 0.

  TAO_Unbounded_String_Sequence (CORBA::ULong maximum);
  // Unbounded sequences provide a constructor that allows only the
  // initial value of the maximum length to be set (the ``maximum
  // constructor'' shown in the example above). This allows
  // applications to control how much buffer space is initially
  // allocated by the sequence. This constructor also sets the length
  // to 0 and the release flag to TRUE.

  TAO_Unbounded_String_Sequence (CORBA::ULong maximum,
                                 CORBA::ULong length,
                                 char **data,
                                 CORBA::Boolean release=0);
  // The ``T *data'' constructor (as shown in the example above)
  // allows the length and contents of a bounded or unbounded sequence
  // to be set. For unbounded sequences, it also allows the initial
  // value of the maximum length to be set. For this constructor,
  // ownership of the contents vector is determined by the release
  // parameter---FALSE means the caller owns the storage, while TRUE
  // means that the sequence assumes ownership of the storage.
  // If release is TRUE, the contents vector must have been allocated
  // using the sequence allocbuf function, and the sequence will pass
  // it to freebuf when finished with it.

  TAO_Unbounded_String_Sequence(const TAO_Unbounded_String_Sequence&);
  // The copy constructor performs a deep copy from the existing
  // structure to create a new structure, including calling _duplicate
  // on all object  reference members and performing the necessary
  // heap allocations for all string members.
  //
  // The copy constructor creates a new sequence with the same maximum
  // and length as the given sequence, copies each of its current
  // elements (items zero through length-1), and sets the release
  // flag to TRUE.

  ~TAO_Unbounded_String_Sequence (void);
  // The destructor releases all object reference members and frees
  // all string members.

  TAO_Unbounded_String_Sequence &operator= (const TAO_Unbounded_String_Sequence &);
  // The assignment operator first releases all object reference
  // members and frees all string  members, and then performs a
  // deep­copy to create a new structure.
  //
  // The assignment operator deep­copies its parameter, releasing
  // old storage if necessary. It behaves as if the original sequence
  // is destroyed via its destructor and then the source sequence
  // copied using the copy constructor. If release=TRUE, the
  // destructor destroys each of the current elements (items zero
  // through length--1).
  // For an unbounded sequence, if a reallocation is necessary due to
  // a change in the length and the sequence was created using the
  // release=TRUE parameter in its constructor, the sequence will
  // deallocate the old storage. If release is FALSE under these
  // circumstances, old storage will not be freed before the
  // reallocation is performed. After reallocation, the release flag
  // is always set to TRUE.

  TAO_String_Manager operator[] (CORBA::ULong index) const;
  // read-write accessor

  static char* *allocbuf (CORBA::ULong);
  // The allocbuf function allocates a vector of T elements that can
  // be passed to the T *data constructor. The length of the vector is
  // given by the nelems function argument.  The allocbuf function
  // initializes each element using its default constructor, except
  // for strings, which are initialized to null pointers, and object
  // references, which are initialized to suitably typed nil object
  // references. A null pointer is returned if allocbuf for some
  // reason cannot allocate the requested vector. Vectors allocated by
  // allocbuf should be freed using the freebuf function.

  static void freebuf (char **);
  // The freebuf function ensures that the destructor for each element
  // is called before the buffer is destroyed, except for string
  // elements, which are freed using string_free(), and object
  // reference elements, which are freed using release(). The freebuf
  // function will ignore null pointers passed to it.

  virtual void _allocate_buffer (CORBA::ULong length);
  virtual void _deallocate_buffer (void);
  virtual void _shrink_buffer (CORBA::ULong new_length,
                               CORBA::ULong old_length);
};

// ****************************************************************

#if defined (TAO_NO_COPY_OCTET_SEQUENCES)
class ACE_Message_Block;
template<class T> class TAO_Unbounded_Sequence;
// forward declaration, we are going to specialize that template
// here.
// The template itself requires this file so every user of the
// template should also see the specialization.

class TAO_Export TAO_Unbounded_Sequence<CORBA::Octet> : public TAO_Unbounded_Base_Sequence
{
  // = TITLE
  //   An unbounded sequence of Octets
  //
  // = DESCRIPTION
  //   Marshalling and demarshalling octet sequences can be highly
  //   optimize, for instance at demarshalling we don't require a copy
  //   from the CDR buffer to the octet sequence buffer, we can simply
  //   hold a duplicate of the underlying ACE_Message_Block.
  //   Specializing the TAO_Unbounded_Sequence<T> parametric
  //   class, is an excellent way to achieve this optimizations.
  //
public:
  friend class TAO_Marshal_Sequence;
  // For efficient marshalling and demarshalling.

  TAO_Unbounded_Sequence (void);
  TAO_Unbounded_Sequence (CORBA::ULong max);
  TAO_Unbounded_Sequence (CORBA::ULong max,
			  CORBA::ULong length,
			  CORBA::Octet *data,
			  CORBA::Boolean release = 0);
  ~TAO_Unbounded_Sequence (void);
  // see TAO_Unbounded_Sequence in "Sequence_T.h"

  TAO_Unbounded_Sequence (const TAO_Unbounded_Sequence<CORBA::Octet> &);
  TAO_Unbounded_Sequence<CORBA::Octet>& operator= (const TAO_Unbounded_Sequence<CORBA::Octet> &);
  // The copy constructor and assignment operators *do* copy the data,
  // though we could simply duplicate the ref count in the
  // ACE_Message_Block this will change the semantics for this
  // operations.

  CORBA::Octet &operator[] (CORBA::ULong);
  const CORBA::Octet &operator[] (CORBA::ULong) const;
  // See the general description in "Sequence_T.h"
  // NOTE: This last two methods can be rendered useless in certain
  // cases, see below.

  // = Static operations.

  static CORBA::Octet *allocbuf (CORBA::ULong);
  // Allocate storage for the sequence, please note that the storage
  // is always held in a ACE_Message_Block.

  static void freebuf (CORBA::Octet *);
  // Free the storage.

  virtual void _allocate_buffer (CORBA::ULong length);
  virtual void _deallocate_buffer (void);
  // Implement the methods for all the sequence, please seee
  // TAO_Base_Sequence.

  // = orbos/98-01-11 proposed extensions.
  CORBA::Octet *get_buffer (CORBA::Boolean orphan = 0);
  const CORBA::Octet *get_buffer (void) const;
  // NOTE: This last two methods can be rendered useless in certain
  // cases, see below.
  void replace (CORBA::ULong max,
                CORBA::ULong length,
                CORBA::Octet *data,
                CORBA::Boolean release = 0);
  // See the general description of this methods in "Sequence_T.h".

  // = TAO extensions

  ACE_Message_Block* mb (void) const;
  // Returns the underlying message block, the caller must *not*
  // release the copy.

  TAO_Unbounded_Sequence (CORBA::ULong length,
			  const ACE_Message_Block* mb);
  // Create a sequence of octets from a single message block (i.e. it
  // ignores any chaining in the meesage block).

  void replace (CORBA::ULong length, const ACE_Message_Block* mb);
  // Replaces the current buffer with <mb>, using only <length> bytes.
  // It takes a duplicate of <mb> so the user still owns it.

  //
  // NOTE:
  // In the last two methods if the <mb> is the head of a chain then
  // the following methods are not warranteed to work properly:
  //    operator[]
  //    get_buffer ()
  // the main purpose of this method is to support custom marshaling;
  // so the complete chain is marshaled when the octet sequence is.
  //

private:
  ACE_Message_Block* mb_;
};

#endif /* defined (TAO_NO_COPY_OCTET_SEQUENCES) */

// ****************************************************************



// ****************************************************************

#if defined (__ACE_INLINE__)
#include "tao/Sequence.i"
#endif /* __ACE_INLINE__ */

#endif /* TAO_SEQUENCE_H */