## NAME

ACE_Data_Block - Stores the data payload that is accessed via one or more `ACE_Message_Block`s.

## SYNOPSIS

    #include <ace/Message_Block.h>

    class ACE_Data_Block
    {
      public:
        ACE_Data_Block (void);
        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
            );
        virtual ~ACE_Data_Block (void);
        ACE_Message_Block::ACE_Message_Type msg_type (void) const;
        void msg_type (ACE_Message_Block::ACE_Message_Type type);
        char *base (void) const;
        void base (
            char *data,
            size_t size,
            ACE_Message_Block::Message_Flags mflags = ACE_Message_Block::DONT_DELETE
            );
        char *end (void) const;
        size_t size (void) const;
        int size (size_t length);
        virtual ACE_Data_Block *clone (
            ACE_Message_Block::Message_Flags mask = 0
            ) const;
        virtual ACE_Data_Block *clone_nocopy (
            ACE_Message_Block::Message_Flags mask = 0
            ) const;
        ACE_Data_Block *duplicate (void);
        ACE_Data_Block *release (ACE_Lock *lock = 0);
        ACE_Message_Block::Message_Flags set_flags (
            ACE_Message_Block::Message_Flags more_flags
            );
        ACE_Message_Block::Message_Flags clr_flags (
            ACE_Message_Block::Message_Flags less_flags
            );
        ACE_Message_Block::Message_Flags flags (void) const;
        ACE_Allocator *allocator_strategy (void) const;
        ACE_Lock *locking_strategy (void);
        ACE_Lock *locking_strategy (ACE_Lock *);
        void dump (void) const;
        int reference_count (void) const;
        ACE_Allocator *data_block_allocator (void) const;
      protected:
        ACE_Data_Block *release_i (void);
        friend class ACE_Message_Block;
        ACE_Data_Block *release_no_delete (ACE_Lock *lock);
        ACE_Message_Block::ACE_Message_Type type_;
        size_t cur_size_;
        size_t max_size_;
        ACE_Message_Block::Message_Flags flags_;
        char *base_;
        ACE_Allocator *allocator_strategy_;
        ACE_Lock *locking_strategy_;
        int reference_count_;
        ACE_Allocator *data_block_allocator_;
      private:
        ACE_Data_Block &operator= (const ACE_Data_Block &);
        ACE_Data_Block (const ACE_Data_Block &);
    };

## 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).

## 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 data in a message.

## Message size is the total amount of space alloted.

    size_t size (void) const;

Get the total amount of space in the message.

    int size (size_t length);

Set the total amount of space in the message. Returns 0 if successful, else -1.

    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

## 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.

## Disallow these operations.

    ACE_Data_Block &operator= (const ACE_Data_Block &);

    ACE_Data_Block (const ACE_Data_Block &);

## AUTHOR

Doug Schmidt

## LIBRARY

ace