--- name: "ACE_Data_Block" section: "3" platform: "linux" package: "libace-doc" version: "5.0.7-4" release: "Debian 2.2 (Potato)" platforms: ["linux"] url: "https://new.carta.tech/ACE_Data_Block" --- # ACE\_Data\_Block(3) Stores the data payload that is accessed via one or more ACE\_Message\_Blocks. ## NAME ACE\_Data\_Block - Stores the data payload that is accessed via one or more ACE\_Message\_Blocks. ## SYNOPSIS ``` #include 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\_Blocks. ``` 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