summaryrefslogtreecommitdiff
path: root/ace/Message_Block.h
blob: b75881a4a8055cbfd4f8d81720fc843531a9e113 (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
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
/* -*- C++ -*- */
// $Id$

// ============================================================================
//
// = LIBRARY
//    ace
//
// = FILENAME
//    Message_Block.h
//
// = AUTHOR
//    Douglas C. Schmidt <schmidt@cs.wustl.edu>
//
// ============================================================================

#include "ace/ACE.h"

#if !defined (ACE_LACKS_PRAGMA_ONCE)
# pragma once
#endif /* ACE_LACKS_PRAGMA_ONCE */

#ifndef ACE_MESSAGE_BLOCK_H
#include "ace/pre.h"
#define ACE_MESSAGE_BLOCK_H

#include "ace/Malloc.h"

// Forward declaration.
class ACE_Data_Block;
class ACE_Lock;
class ACE_Time_Value;

class ACE_Export ACE_Message_Block
{
  // = TITLE
  //     Stores messages for use throughout ACE (particularly
  //     <ACE_Message_Queue>).
  //
  // = DESCRIPTION
  //     An <ACE_Message_Block> is modeled after the message data
  //     structures used in System V STREAMS.  Its purpose is to
  //     enable efficient manipulation of arbitrarily-large messages
  //     without much incurring memory copying overhead.  Here are the
  //     main characteristics of an <ACE_Message_Block>:
  //
  //     1. Contains a pointer to a reference-counted
  //     <ACE_Data_Block>, which in turn points to the actual data
  //     buffer.  This allows very flexible and efficient sharing of
  //     data by multiple <ACE_Message_Block>s.
  //
  //     2. One or more <ACE_Message_Blocks> can be linked to form a
  //     ``fragment chain.''
  //
  //     3. <ACE_Message_Blocks> can be linked together by <prev_> and
  //     <next_> pointers to form a queue of messages (e.g., this is how
  //     <ACE_Message_Queue> works).
public:
  friend class ACE_Data_Block;

  enum
  {
    // = Data and protocol messages (regular and priority)
    MB_DATA     = 0x01, // regular data
    MB_PROTO    = 0x02, // protocol control

    // = Control messages (regular and priority)
    MB_BREAK    = 0x03, // line break
    MB_PASSFP   = 0x04, // pass file pointer
    MB_EVENT    = 0x05, // post an event to an event queue
    MB_SIG      = 0x06, // generate process signal
    MB_IOCTL    = 0x07, // ioctl; set/get params
    MB_SETOPTS  = 0x08, // set various stream head options

    // = Control messages (high priority; go to head of queue)
    MB_IOCACK   = 0x81, // acknowledge ioctl
    MB_IOCNAK   = 0x82, // negative ioctl acknowledge
    MB_PCPROTO  = 0x83, // priority proto message
    MB_PCSIG    = 0x84, // generate process signal
    MB_READ     = 0x85, // generate read notification
    MB_FLUSH    = 0x86, // flush your queues
    MB_STOP     = 0x87, // stop transmission immediately
    MB_START    = 0x88, // restart transmission after stop
    MB_HANGUP   = 0x89, // line disconnect
    MB_ERROR    = 0x8a, // fatal error used to set u.u_error
    MB_PCEVENT  = 0x8b, // post an event to an event queue

    // Message class masks
    MB_NORMAL   = 0x00, // Normal priority messages
    MB_PRIORITY = 0x80, // High priority control messages
    MB_USER     = 0x200 // User-defined control messages
  };

  typedef int ACE_Message_Type;
  typedef u_long Message_Flags;

  enum
  {
    DONT_DELETE = 01, // Don't delete the data on exit since we don't own it.
    USER_FLAGS = 0x1000 // user defined flags start here
  };

  // = Initialization and termination.
  ACE_Message_Block (ACE_Allocator *message_block_allocator = 0);
  // Create an empty message.

  ACE_Message_Block (ACE_Data_Block *,
                     ACE_Allocator *message_block_allocator = 0);
  // Create an <ACE_Message_Block> that owns the <ACE_Data_Block> *.

  ACE_Message_Block (const char *data,
                     size_t size = 0,
                     u_long priority = ACE_DEFAULT_MESSAGE_BLOCK_PRIORITY);
  // Create a Message Block that assumes ownership of <data> without
  // copying it (i.e., we don't delete it since we don't malloc it!).
  // Note that the <size> of the <Message_Block> will be <size>, but
  // the <length> will be 0 until <wr_ptr> is set.

  ACE_Message_Block (size_t size,
                     ACE_Message_Type type = MB_DATA,
                     ACE_Message_Block *cont = 0,
                     const char *data = 0,
                     ACE_Allocator *allocator_strategy = 0,
                     ACE_Lock *locking_strategy = 0,
                     u_long priority = ACE_DEFAULT_MESSAGE_BLOCK_PRIORITY,
                     const ACE_Time_Value &execution_time = ACE_Time_Value::zero,
                     const ACE_Time_Value &deadline_time = ACE_Time_Value::max_time,
                     ACE_Allocator *data_block_allocator = 0,
                     ACE_Allocator *message_block_allocator = 0);
  // Create an initialized message of type <type> containing <size>
  // bytes.  The <cont> argument initializes the continuation field in
  // the <Message_Block>.  If <data> == 0 then we create and own the
  // <data>, using <allocator> to get the data if it's non-0.  If
  // <data> != 0 we assume ownership of the <data> (and don't delete
  // it).  If <locking_strategy> is non-0 then this is used to protect
  // regions of code that access shared state (e.g., reference
  // counting) from race conditions.  Note that the <size> of the
  // <Message_Block> will be <size>, but the <length> will be 0 until
  // <wr_ptr> is set.
  // The <data_block_allocator> is use to allocate the data blocks
  // while the <allocator_strategy> is used to allocate the buffers
  // contained by those.
  // The <message_block_allocator> is used to allocate new
  // <Message_Block> objects when a duplicate method is called.  If
  // a <message_block_allocator> is given, this <Message_Block> and
  // future <Message_Block> objects created by duplicate will be free'ed
  // into this allocator when they are released.  Note: if you use this
  // allocator, the <Message_Block> you created should have been created
  // using this allocator because it will be released to the same allocator.

  int init (const char *data,
            size_t size = 0);
  // Create a Message Block that assumes ownership of <data> (i.e.,
  // doesn't delete it since it didn't malloc it!).  Note that the
  // <size> of the <Message_Block> will be <size>, but the <length>
  // will be 0 until <wr_ptr> is set.

  int init (size_t size,
            ACE_Message_Type type = MB_DATA,
            ACE_Message_Block *cont = 0,
            const char *data = 0,
            ACE_Allocator *allocator_strategy = 0,
            ACE_Lock *locking_strategy = 0,
            u_long priority = ACE_DEFAULT_MESSAGE_BLOCK_PRIORITY,
            const ACE_Time_Value &execution_time = ACE_Time_Value::zero,
            const ACE_Time_Value &deadline_time = ACE_Time_Value::max_time,
            ACE_Allocator *data_block_allocator = 0,
            ACE_Allocator *message_block_allocator = 0);
  // Create an initialized message of type <type> containing <size>
  // bytes.  The <cont> argument initializes the continuation field in
  // the <Message_Block>.  If <data> == 0 then we create and own the
  // <data>, using <allocator> to get the data if it's non-0.  If
  // <data> != 0 we assume ownership of the <data> (and don't delete
  // it).  If <locking_strategy> is non-0 then this is used to protect
  // regions of code that access shared state (e.g., reference
  // counting) from race conditions.  Note that the <size> of the
  // <Message_Block> will be <size>, but the <length> will be 0 until
  // <wr_ptr> is set.
  // The <data_block_allocator> is use to allocate the data blocks
  // while the <allocator_strategy> is used to allocate the buffers
  // contained by those.

  virtual ~ACE_Message_Block (void);
  // Delete all the resources held in the message.
  //
  // Note that <release> is designed to release the continuation
  // chain; the destructor is not. See <release> for details.

  // = Message Type accessors and mutators.

  ACE_Message_Type msg_type (void) const;
  // Get type of the message.

  void msg_type (ACE_Message_Type type);
  // Set type of the message.

  int is_data_msg (void) const;
  // Find out what type of message this is.

  ACE_Message_Type msg_class (void) const;
  // Find out what class of message this is (there are two classes,
  // <normal> messages and <high-priority> messages).

  // = Message flag accessors and mutators.
  Message_Flags set_flags (Message_Flags more_flags);
  // Bitwise-or the <more_flags> into the existing message flags and
  // return the new value.

  Message_Flags clr_flags (Message_Flags less_flags);
  // Clear the message flag bits specified in <less_flags> and return
  // the new value.

  Message_Flags flags (void) const;
  // Get the current message flags.

  u_long msg_priority (void) const;
  // Get priority of the message.

  void msg_priority (u_long priority);
  // Set priority of the message.

  const ACE_Time_Value &msg_execution_time (void) const;
  // Get execution time associated with the message.

  void msg_execution_time (const ACE_Time_Value &et);
  // Set execution time associated with the message.

  const ACE_Time_Value &msg_deadline_time (void) const;
  // Get absolute time of deadline associated with the message.

  void msg_deadline_time (const ACE_Time_Value &dt);
  // Set absolute time of deadline associated with the message.

  // = Deep copy and shallow copy methods.

  virtual ACE_Message_Block *clone (Message_Flags mask = 0) const;
  // Return an exact "deep copy" of the message, i.e., create fresh
  // new copies of all the Data_Blocks and continuations.

  ACE_Message_Block *duplicate (void) const;
  // Return a "shallow" copy that increments our reference count by 1.

  static ACE_Message_Block *duplicate (const ACE_Message_Block *mb);
  // Return a "shallow" copy that increments our reference count by 1.
  // This is similar to CORBA's <_duplicate> method, which is useful
  // if you want to eliminate lots of checks for NULL <mb> pointers
  // before calling <_duplicate> on them.

  ACE_Message_Block *release (void);
  // Decrease the shared ACE_Data_Block's reference count by 1.  If the
  // ACE_Data_Block's reference count goes to 0, it is deleted.
  // In all cases, this ACE_Message_Block is deleted - it must have come
  // from the heap, or there will be trouble.
  //
  // <release> is designed to release the continuation chain; the
  // destructor is not.  If we make the destructor release the
  // continuation chain by calling <release> or delete on the message
  // blocks in the continuation chain, the following code will not
  // work since the message block in the continuation chain is not off
  // the heap:
  //
  //  ACE_Message_Block mb1 (1024);
  //  ACE_Message_Block mb2 (1024);
  //
  //  mb1.cont (&mb2);
  //
  // And hence, call <release> on a dynamically allocated message
  // block. This will release all the message blocks in the
  // continuation chain.  If you call delete or let the message block
  // fall off the stack, cleanup of the message blocks in the
  // continuation chain becomes the responsibility of the user.

  static ACE_Message_Block *release (ACE_Message_Block *mb);
  // This behaves like the non-static method <release>, except that it
  // checks if <mb> is 0.  This is similar to <CORBA::release>, which
  // is useful if you want to eliminate lots of checks for NULL
  // pointers before calling <release> on them.  Returns <mb>.

  // = Operations on Message data

  int copy (const char *buf, size_t n);
  // Copies <n> bytes from <buf> into the Message_Block starting at
  // the <wr_ptr> offset.  Return 0 and increment <wr_ptr> by <n> if
  // the method succeeds.  Returns -1 if the size of the message is
  // too small, i.e., for this to work correct, <end> must be >=
  // <wr_ptr>.

  int copy (const char *buf);
  // Copies <buf> into the Message_Block starting at the <wr_ptr>
  // offset.  This call assumees that <buf> is NUL-terminated.  Return
  // 0 and increment <wr_ptr> by <ACE_OS::strlen (buf) + 1> if the
  // method succeeds.  Returns -1 if the size of the message is too
  // small, i.e., for this to work correct, <end> must be >= <wr_ptr>.

  void crunch (void);
  // Normalizes data in the top-level <Message_Block> to align with the base.

  void reset (void);
  // Resets the Message Block data to contain nothing, i.e., sets the
  // read and write pointers to align with the base.

  char *base (void) const;
  // Get message data.

  void base (char *data,
             size_t size,
             Message_Flags = DONT_DELETE);
  // Set message data (doesn't reallocate).

  char *end (void) const;
  // Return a pointer to 1 past the end of the allocated data in a message.

  char *mark (void) const;
  // Return a pointer to 1 past the end of the allotted data in a message.
  // Allotted data may be less than allocated data  if a value smaller than
  // capacity() to is passed to size().

  char *rd_ptr (void) const;
  // Get the read pointer.
  void rd_ptr (char *ptr);
  // Set the read pointer to <ptr>.
  void rd_ptr (size_t n);
  // Set the read pointer ahead <n> bytes.

  char *wr_ptr (void) const;
  // Get the write pointer.
  void wr_ptr (char *ptr);
  // Set the write pointer to <ptr>.
  void wr_ptr (size_t n);
  // Set the write pointer ahead <n> bytes.  This is used to compute
  // the <length> of a message.

  // = Message length is <wr_ptr> - <rd_ptr>.
  size_t length (void) const;
  // Get the length of the message
  void length (size_t n);
  // Set the length of the message
  size_t total_length (void) const;
  // Get the length of the <Message_Block>s, including chained
  // <Message_Block>s.

  // = Set/get <Message_Block> size info.
  size_t total_size (void) const;
  // Get the total number of bytes in all <Message_Block>s, including
  // chained <Message_Block>s.

  size_t size (void) const;
  // Get the number of bytes in the top-level <Message_Block> (i.e.,
  // does not consider the bytes in chained <Message_Block>s).

  int size (size_t length);
  // Set the number of bytes in the top-level <Message_Block>,
  // reallocating space if necessary.  However, the <rd_ptr_> and
  // <wr_ptr_> remain at the original offsets into the buffer, even if
  // it is reallocated.  Returns 0 if successful, else -1.

  size_t total_capacity (void) const;
  // Get the number of allocated bytes in all <Message_Block>, including
  // chained <Message_Block>s.

  size_t capacity (void) const;
  // Get the number of allocated bytes in the top-level <Message_Block>.

  size_t space (void) const;
  // Get the number of bytes available after the <wr_ptr_> in the
  // top-level <Message_Block>.

  // = <ACE_Data_Block> methods.

  ACE_Data_Block *data_block (void) const;
  // Get a pointer to the data block. Note that the <ACE_Message_Block>
  // still references the block; this call does not change the reference
  // count.

  void data_block (ACE_Data_Block *);
  // Set a new data block pointer. The original <ACE_Data_Block> is released
  // as a result of this call. If you need to keep the original block, call
  // <replace_data_block> instead. Upon return, this <ACE_Message_Block>
  // holds a pointer to the new <ACE_Data_Block>, taking over the reference
  // you held on it prior to the call.

  ACE_Data_Block *replace_data_block (ACE_Data_Block*);
  // Set a new data block pointer. A pointer to the original <ACE_Data_Block>
  // is returned, and not released (as it is with <data_block>).

  // = The continuation field chains together composite messages.
  ACE_Message_Block *cont (void) const;
  // Get the continuation field.
  void cont (ACE_Message_Block *);
  // Set the continuation field.

  // = Pointer to the <Message_Block> directly ahead in the <ACE_Message_Queue>.
  ACE_Message_Block *next (void) const;
  // Get link to next message.
  void next (ACE_Message_Block *);
  // Set link to next message.

  // = Pointer to the <Message_Block> directly behind in the <ACE_Message_Queue>.
  ACE_Message_Block *prev (void) const;
  // Get link to prev message.
  void prev (ACE_Message_Block *);
  // Set link to prev message.

  // = The locking strategy prevents race conditions.
  ACE_Lock *locking_strategy (void);
  // Get the locking strategy.
  ACE_Lock *locking_strategy (ACE_Lock *);
  // Set a new locking strategy and return the hold one.

  int reference_count (void) const;
  // Get the current reference count.

  void dump (void) const;
  // Dump the state of an object.

  ACE_ALLOC_HOOK_DECLARE;
  // Declare the dynamic allocation hooks.

protected:
  // = Internal initialization methods.
  ACE_Message_Block (size_t size,
                     ACE_Message_Type type,
                     ACE_Message_Block *cont,
                     const char *data,
                     ACE_Allocator *allocator_strategy,
                     ACE_Lock *locking_strategy,
                     Message_Flags flags,
                     u_long priority,
                     const ACE_Time_Value &execution_time,
                     const ACE_Time_Value &deadline_time,
                     ACE_Data_Block *db,
                     ACE_Allocator *data_block_allocator,
                     ACE_Allocator *message_block_allocator);
  // Perform the actual initialization.

  int release_i (ACE_Lock *lock);
  // Internal release implementation
  // Returns 1 if the data block has to be destroyed.

  int init_i (size_t size,
              ACE_Message_Type type,
              ACE_Message_Block *cont,
              const char *data,
              ACE_Allocator *allocator_strategy,
              ACE_Lock *locking_strategy,
              Message_Flags flags,
              u_long priority,
              const ACE_Time_Value &execution_time,
              const ACE_Time_Value &deadline_time,
              ACE_Data_Block *db,
              ACE_Allocator *data_block_allocator,
              ACE_Allocator *message_block_allocator);
  // Perform the actual initialization.

  size_t rd_ptr_;
  // Pointer to beginning of next read.

  size_t wr_ptr_;
  // Pointer to beginning of next write.

  u_long priority_;
  // Priority of message.

#if defined (ACE_HAS_TIMED_MESSAGE_BLOCKS)
  ACE_Time_Value execution_time_;
  // execution time associated with the message

  ACE_Time_Value deadline_time_;
  // absolute deadline time for message
#endif /* ACE_HAS_TIMED_MESSAGE_BLOCKS */

  // = Links to other ACE_Message_Block *s.
  ACE_Message_Block *cont_;
  // Pointer to next message block in the chain.

  ACE_Message_Block *next_;
  // Pointer to next message in the list.

  ACE_Message_Block *prev_;
  // Pointer to previous message in the list.

  ACE_Data_Block *data_block_;
  // Pointer to the reference counted data structure that contains the
  // actual memory buffer.

  ACE_Allocator *message_block_allocator_;
  // The allocator used to destroy ourselves when release is called
  // and create new message blocks on duplicate.

private:
  // = Disallow these operations for now (use <clone> instead).
  ACE_Message_Block &operator= (const ACE_Message_Block &);
  ACE_Message_Block (const ACE_Message_Block &);
};

class ACE_Export ACE_Data_Block
{
  // = TITLE
  //     Stores the data payload that is accessed via one or more
  //     <ACE_Message_Block>s.
  //
  // = DESCRIPTION
  //     This data structure is reference counted to maximize
  //     sharing.  It also contains the <locking_strategy_> (which
  //     protects the reference count from race conditions in
  //     concurrent programs) and the <allocation_strategy_> (which
  //     determines what memory pool is used to allocate the memory).
public:
  // = Initialization and termination methods.
  ACE_Data_Block (void);
  // Default "do-nothing" constructor.

  ACE_Data_Block (size_t size,
                  ACE_Message_Block::ACE_Message_Type msg_type,
                  const char *msg_data,
                  ACE_Allocator *allocator_strategy,
                  ACE_Lock *locking_strategy,
                  ACE_Message_Block::Message_Flags flags,
                  ACE_Allocator *data_block_allocator);
  // Initialize.

  virtual ~ACE_Data_Block (void);
  // Delete all the resources held in the message.

  ACE_Message_Block::ACE_Message_Type msg_type (void) const;
  // Get type of the message.

  void msg_type (ACE_Message_Block::ACE_Message_Type type);
  // Set type of the message.

  char *base (void) const;
  // Get message data pointer

  void base (char *data,
             size_t size,
             ACE_Message_Block::Message_Flags mflags = ACE_Message_Block::DONT_DELETE);
  // Set message data pointer (doesn't reallocate).

  char *end (void) const;
  // Return a pointer to 1 past the end of the allocated data in a message.

  char *mark (void) const;
  // Return a pointer to 1 past the end of the allotted data in a message.
  // The allotted data may be less than allocated data if <size()> is passed
  // an argument less than <capacity()>.

  // = Message size is the total amount of space alloted.

  size_t size (void) const;
  // Get the total amount of allotted space in the message.  The amount of
  // allotted space may be less than allocated space.

  int size (size_t length);
  // Set the total amount of space in the message.  Returns 0 if
  // successful, else -1.

  size_t capacity (void) const;
  // Get the total amount of allocated space.

  virtual ACE_Data_Block *clone (ACE_Message_Block::Message_Flags mask = 0) const;
  // Return an exact "deep copy" of the message, i.e., create fresh
  // new copies of all the Data_Blocks and continuations.
  // Notice that Data_Blocks can act as "Prototypes", i.e. derived
  // classes can override this method and create instances of
  // themselves.

  virtual ACE_Data_Block *clone_nocopy (ACE_Message_Block::Message_Flags mask = 0) const;
  // As clone above, but it does not copy the contents of the buffer,
  // i.e., create a new Data_Block of the same dynamic type, with the
  // same allocator, locking_strategy, and with the same amount of
  // storage available but the buffer is unitialized.

  ACE_Data_Block *duplicate (void);
  // Return a "shallow" copy that increments our reference count by 1.

  ACE_Data_Block *release (ACE_Lock *lock = 0);
  // Decrease the shared reference count by 1.  If the reference count
  // is > 0 then return this; else if reference count == 0 then delete
  // <this> and <mb> and return 0.  Behavior is undefined if reference
  // count < 0.

  // = Message flag accessors and mutators.
  ACE_Message_Block::Message_Flags set_flags (ACE_Message_Block::Message_Flags more_flags);
  // Bitwise-or the <more_flags> into the existing message flags and
  // return the new value.

  ACE_Message_Block::Message_Flags clr_flags (ACE_Message_Block::Message_Flags less_flags);
  // Clear the message flag bits specified in <less_flags> and return
  // the new value.

  ACE_Message_Block::Message_Flags flags (void) const;
  // Get the current message flags.

  ACE_Allocator *allocator_strategy (void) const;
  // Obtain the allocator strategy.

  // = The locking strategy prevents race conditions.
  ACE_Lock *locking_strategy (void);
  // Get the locking strategy.
  ACE_Lock *locking_strategy (ACE_Lock *);
  // Set a new locking strategy and return the hold one.

  void dump (void) const;
  // Dump the state of an object.

  int reference_count (void) const;
  // Get the current reference count.

  ACE_Allocator *data_block_allocator (void) const;
  // Get the allocator used to create this object

protected:
  ACE_Data_Block *release_i (void);
  // Internal release implementation

  friend class ACE_Message_Block;
  ACE_Data_Block *release_no_delete (ACE_Lock *lock);
  // Decrease the reference count, but don't delete the object.
  // Returns 0 if the object should be removed.
  // If <lock> is equal to the locking strategy then we assume that
  // the lock is beign held by the current thread; this is used to
  // release all the data blocks in a chain while holding a single
  // lock.

  ACE_Message_Block::ACE_Message_Type type_;
  // Type of message.

  size_t cur_size_;
  // Current size of message block.

  size_t max_size_;
  // Total size of buffer.

  ACE_Message_Block::Message_Flags flags_;
  // Misc flags (e.g., DONT_DELETE and USER_FLAGS).

  char *base_;
  // Pointer to beginning of message payload.

  // = Strategies.
  ACE_Allocator *allocator_strategy_;
  // Pointer to the allocator defined for this <ACE_Data_Block>.  Note
  // that this pointer is shared by all owners of this
  // <ACE_Data_Block>.

  ACE_Lock *locking_strategy_;
  // Pointer to the locking strategy defined for this
  // <ACE_Data_Block>.  This is used to protect regions of code that
  // access shared <ACE_Data_Block> state.  Note that this lock is
  // shared by all owners of the <ACE_Data_Block>'s data.

  int reference_count_;
  // Reference count for this <ACE_Data_Block>, which is used to avoid
  // deep copies (i.e., <clone>).  Note that this pointer value is
  // shared by all owners of the <Data_Block>'s data, i.e., all the
  // <ACE_Message_Block>s.

  ACE_Allocator *data_block_allocator_;
  // The allocator use to destroy ourselves.

private:
  // = Disallow these operations.
  ACE_Data_Block &operator= (const ACE_Data_Block &);
  ACE_Data_Block (const ACE_Data_Block &);
};

class ACE_Export ACE_Dynamic_Message_Strategy
{
  // = TITLE
  //     An abstract base class which provides dynamic priority
  //     evaluation methods for use by the <ACE_Dynamic_Message_Queue>
  //     class or any other class which needs to manage the priorities
  //     of a collection of <ACE_Message_Block>s dynamically.
  //
  // = DESCRIPTION
  //     Methods for deadline and laxity based priority evaluation are
  //     provided.  These methods assume a specific partitioning of
  //     the message priority number into a higher order dynamic bit
  //     field and a lower order static priority bit field.  The
  //     default partitioning assumes an unsigned dynamic message
  //     priority field of 22 bits and an unsigned static message
  //     priority field of 10 bits.  This corresponds to the initial
  //     values of the static class members.  To provide a different
  //     partitioning, assign a different set of values to the static
  //     class memebers before using the static member functions.
public:

  // = Message priority status

  // Values are defined as bit flags so that status combinations may
  // be specified easily.

  enum Priority_Status
  {
    PENDING     = 0x01, // message can still make its deadline
    LATE        = 0x02, // message cannot make its deadline
    BEYOND_LATE = 0x04, // message is so late its priority is undefined
    ANY_STATUS  = 0x07  // mask to match any priority status
  };

  ACE_Dynamic_Message_Strategy (u_long static_bit_field_mask,
                                u_long static_bit_field_shift,
                                u_long dynamic_priority_max,
                                u_long dynamic_priority_offset);
  // ctor

  virtual ~ACE_Dynamic_Message_Strategy (void);
  // virtual dtor

  Priority_Status priority_status (ACE_Message_Block &mb,
                                   const ACE_Time_Value &tv);
  // Updates the message's priority and returns its priority status.

  u_long static_bit_field_mask (void);
  // Get static bit field mask.

  void static_bit_field_mask (u_long);
  // Set static bit field mask.

  u_long static_bit_field_shift (void);
  // Get left shift value to make room for static bit field.

  void static_bit_field_shift (u_long);
  // Set left shift value to make room for static bit field.

  u_long dynamic_priority_max (void);
  // Get maximum supported priority value.

  void dynamic_priority_max (u_long);
  // Set maximum supported priority value.

  u_long dynamic_priority_offset (void);
  // Get offset to boundary between signed range and unsigned range.

  void dynamic_priority_offset (u_long);
  // Set offset to boundary between signed range and unsigned range.

  virtual void dump (void) const;
  // Dump the state of the strategy.

protected:
  virtual void convert_priority (ACE_Time_Value &priority,
                                 const ACE_Message_Block &mb) = 0;
  // Hook method for dynamic priority conversion.

  u_long static_bit_field_mask_;
  // This is a bit mask with all ones in the static bit field.

  u_long static_bit_field_shift_;
  // This is a left shift value to make room for static bit field:
  // this value should be the logarithm base 2 of
  // (static_bit_field_mask_ + 1).

  u_long dynamic_priority_max_;
  // Maximum supported priority value.

  u_long dynamic_priority_offset_;
  // Offset to boundary between signed range and unsigned range.

  ACE_Time_Value max_late_;
  // Maximum late time value that can be represented.

  ACE_Time_Value min_pending_;
  // Minimum pending time value that can be represented.

  ACE_Time_Value pending_shift_;
  // Time value by which to shift pending priority.
};

class ACE_Export ACE_Deadline_Message_Strategy : public ACE_Dynamic_Message_Strategy
{
  // = TITLE
  //     Deadline based message priority strategy.
  //
  // = DESCRIPTION
  //     Assigns dynamic message priority according to time to deadline.  The
  //     message priority is divided into high and low order bit fields.  The
  //     high order bit field is used for dynamic message priority, which is
  //     updated whenever the convert_priority (...) method is called.  The
  //     low order bit field is used for static message priority and is left
  //     unchanged.  The partitioning of the priority value into high and low
  //     order bit fields is done according to the arguments passed to the
  //     strategy object's constructor.
  //
public:
  ACE_Deadline_Message_Strategy (u_long static_bit_field_mask = 0x3FFUL,       // 2^(10) - 1
                                 u_long static_bit_field_shift = 10,           // 10 low order bits
                                 u_long dynamic_priority_max = 0x3FFFFFUL,     // 2^(22)-1
                                 u_long dynamic_priority_offset = 0x200000UL); // 2^(22-1)
  // Ctor, with all arguments defaulted.

  virtual ~ACE_Deadline_Message_Strategy (void);
  // Virtual dtor.

  virtual void convert_priority (ACE_Time_Value &priority,
                                 const ACE_Message_Block &mb);
  // Dynamic priority conversion function based on time to deadline.

  virtual void dump (void) const;
  // Dump the state of the strategy.
};

class ACE_Export ACE_Laxity_Message_Strategy : public ACE_Dynamic_Message_Strategy
{
  // = TITLE
  //     Laxity based message priority strategy.
  //
  // = DESCRIPTION
  //     Assigns dynamic message priority according to laxity (time to
  //     deadline minus worst case execution time).  The message priority is
  //     divided into high and low order bit fields.  The high order
  //     bit field is used for dynamic message priority, which is
  //     updated whenever the convert_priority (...) method is called.  The
  //     low order bit field is used for static message priority and is left
  //     unchanged.  The partitioning of the priority value into high and low
  //     order bit fields is done according to the arguments passed to the
  //     strategy object's constructor.
  //
public:
  ACE_Laxity_Message_Strategy (u_long static_bit_field_mask = 0x3FFUL,       // 2^(10) - 1
                               u_long static_bit_field_shift = 10,           // 10 low order bits
                               u_long dynamic_priority_max = 0x3FFFFFUL,     // 2^(22)-1
                               u_long dynamic_priority_offset = 0x200000UL); // 2^(22-1)
  // Ctor, with all arguments defaulted.

  virtual ~ACE_Laxity_Message_Strategy (void);
  // virtual dtor.

  virtual void convert_priority (ACE_Time_Value &priority,
                                 const ACE_Message_Block &mb);
  // Dynamic priority conversion function based on laxity.

  virtual void dump (void) const;
  // Dump the state of the strategy.
};

#if defined (__ACE_INLINE__)
#include "ace/Message_Block.i"
#endif /* __ACE_INLINE__ */

#include "ace/Message_Block_T.h"
#include "ace/post.h"
#endif /* ACE_MESSAGE_BLOCK_H */