Difference between revisions of "Data Overview"

From reSIProcate
Jump to navigation Jump to search
(Data memory management)
 
Line 11: Line 11:
 
but will guarantee that the internal buffer is null terminated, by
 
but will guarantee that the internal buffer is null terminated, by
 
copying it if necessary.
 
copying it if necessary.
 
Data is in one of three states with respect to its contents' memory.
 
1. Share
 
2. Borrow
 
3. Take
 
 
'Share' means that the instance contents' memory is overlayed from
 
someone else's memory. It must be guaranteed that the shared memory
 
will not be reclaimed or modified while the Data instance exists. The
 
instance will not write to its shared contents. Responsibility for
 
deleting the memory is outside of the Data instance.
 
 
The Share state is typically used when parsing a SipMessage. The
 
SipMessage's buffers of text are shared to the Data instances rather
 
than copied.
 
 
Usually, sharing occurs under the hood during parsing. However,
 
sharing can be made to occur with ParseBuffer::data(...).
 
 
'Borrow' means that the instance contents' memory is from an outside
 
scope but may be modified through the Data instance. It must be
 
guaranteed that the borrowed memory will not be reclaimed or modified
 
while the Data instance exists. Again, responibility for deleting the
 
memory is elsewhere.
 
 
The Borrow state is often used for short strings. Each Data instance
 
has a small inline buffer that can be borrowed to handle small strings
 
without additional heap allocation. The size of this internal buffer
 
is determined at compile time. A typical value is 16.
 
 
Borrow state can also be useful to explicitly allocate a Data
 
instance's memory from the stack rather than from the heap. Note that
 
if the stack allocation proves too small, the Data instance will
 
transition to using heap memory at the cost of copying the contents.
 
 
char buffer[256];
 
Data cmd(Data::Borrow, buffer, sizeof(buffer));
 
cmd.clear();  // or cmd will be full of stack junk
 
 
'Take' means that the instance contents' memory is owned by the Data
 
instance and can be modified as needed. In this state, the
 
Data instance has responsibility for deleting the memory.
 
 
An instance of Data can transition from Share to Take or from Borrow
 
to Take or from Take to Take. In each transition, new memory is
 
allocated for the contents. Only in the Take to Take transition is the
 
old memory deleted. A Take to Take transition occcurs when, for
 
example, the content length exceeds the current memory allocation.
 

Revision as of 19:27, 15 November 2004

Data is resiprocate's string class. It is named Data rather than String for historical reasons. VOCAL had a reference counting version of Data. Resiprocate's version is not reference counting.

Data handles 8 bit character buffers.

Data is internally aware of its content length and is not guaranteed to be null terminated. Date::data() returns a raw pointer to internal memory. Data::c_str() also returns a raw pointer to internal memory, but will guarantee that the internal buffer is null terminated, by copying it if necessary.