Main Page | Modules | Namespace List | Class Hierarchy | Data Structures | Directories | File List | Namespace Members | Data Fields | Globals

alp::SharedBuffer Class Reference
[CoreSupportUtilities]

#include <include/hiker/prv/support/SharedBuffer.h>


Detailed Description

A chunk of memory that supports copy-on-write semantics.

A class for managing raw blocks of memory, which also includes support for sharing among multiple users with copy-on-write semantics.

To correctly use the class, you will usually keep a const SharedBuffer* to your buffer, and call Edit() when you would like to modify its data. This ensures you follow the correct copy-on-write semantics, not allowing you to modify a buffer if it has more than one user.

Note:
Because you do not own this memory, you can not place anything in it for which you must do some cleanup when freeing its memory. (For example, the memory can not contain pointer to binders or any other SAtom-derived class, which will need a Release() call when the shared buffer it is in goes away.)


Public Types

typedef void(* inc_ref_func )()
typedef void(* dec_ref_func )()

Public Member Functions

const void * Data () const
 Return a read-only version of the buffer's data.
void * Data ()
 Return a read/write version of the buffer's data.
size_t Length () const
 Return the number of bytes in this buffer.
void IncUsers () const
 Add a user to the buffer.
void DecUsers () const
 Remove a user from the buffer.
int32_t Users () const
 Return the number of users this buffer has.
SharedBufferEdit (size_t newLength) const
 Given a read-only buffer, start modifying it.
SharedBufferEdit () const
 Edit() without changing size.
const SharedBufferPool () const
 Place the shared buffer into the process's buffer pool.
int32_t Compare (const SharedBuffer *other) const
 Perform a comparison of the data in two buffers.
SharedBufferBeginBuffering ()
 Convert this SharedBuffer to buffering mode.
SharedBufferEndBuffering ()
 Stop buffering mode started with BeginBuffering().
bool Buffering () const
 Is BeginBuffering() mode active?
size_t BufferSize () const
 How big is the actual size of the buffer?
void IncStrong (const void *) const
 Synonym for IncUsers(), for compatibility with sptr<>.
void DecStrong (const void *) const
 Synonym for DecUsers(), for compatibility with sptr<>.
void IncStrongFast () const
 Synonym for IncUsers(), for compatibility with sptr<>.
void DecStrongFast () const
 Synonym for DecUsers(), for compatibility with sptr<>.

Static Public Member Functions

static SharedBufferAlloc (size_t length)
 Create a new buffer of the given size.
static const SharedBufferBufferFromData (const void *data)
 Inverse of Data().


Member Typedef Documentation

typedef void(* alp::SharedBuffer::dec_ref_func)()
 

typedef void(* alp::SharedBuffer::inc_ref_func)()
 


Member Function Documentation

static SharedBuffer* alp::SharedBuffer::Alloc size_t  length  )  [static]
 

Create a new buffer of the given size.

A buffer starts out with a user count of 1; call DecUsers() to free it.

SharedBuffer* alp::SharedBuffer::BeginBuffering  ) 
 

Convert this SharedBuffer to buffering mode.

Buffering mode is more efficient for a serious of operations that will increase or decrease the size of the buffer each time. Call EndBuffering() when done.

const SharedBuffer * alp::SharedBuffer::BufferFromData const void *  data  )  [inline, static]
 

Inverse of Data().

Given a data pointer returned by Data(), returns the SharedBuffer that the pointer came from. This exists largely for the use of String, which likes to store just the pointer to its string data. In general, it's better to store a pointer to the SharedBuffer, and use Data() to access its data.

bool alp::SharedBuffer::Buffering  )  const
 

Is BeginBuffering() mode active?

size_t alp::SharedBuffer::BufferSize  )  const
 

How big is the actual size of the buffer?

int32_t alp::SharedBuffer::Compare const SharedBuffer other  )  const
 

Perform a comparison of the data in two buffers.

Returns:
< 0 if this is less than other; > 0 if this is greater than other; 0 if they are identical.

void * alp::SharedBuffer::Data  )  [inline]
 

Return a read/write version of the buffer's data.

Note:
You MUST call Edit() to ensure you are the sole owner of this buffer, before modifying its data.
See also:
Edit()

const void * alp::SharedBuffer::Data  )  const [inline]
 

Return a read-only version of the buffer's data.

void alp::SharedBuffer::DecStrong const void *   )  const [inline]
 

Synonym for DecUsers(), for compatibility with sptr<>.

void alp::SharedBuffer::DecStrongFast  )  const [inline]
 

Synonym for DecUsers(), for compatibility with sptr<>.

void alp::SharedBuffer::DecUsers  )  const
 

Remove a user from the buffer.

If you are the last user, the buffer is deallocated.

SharedBuffer* alp::SharedBuffer::Edit  )  const
 

Edit() without changing size.

SharedBuffer* alp::SharedBuffer::Edit size_t  newLength  )  const
 

Given a read-only buffer, start modifying it.

If the buffer currently has multiple users, it will be copied and a new one returned to you.

SharedBuffer* alp::SharedBuffer::EndBuffering  ) 
 

Stop buffering mode started with BeginBuffering().

void alp::SharedBuffer::IncStrong const void *   )  const [inline]
 

Synonym for IncUsers(), for compatibility with sptr<>.

void alp::SharedBuffer::IncStrongFast  )  const [inline]
 

Synonym for IncUsers(), for compatibility with sptr<>.

void alp::SharedBuffer::IncUsers  )  const
 

Add a user to the buffer.

size_t alp::SharedBuffer::Length  )  const [inline]
 

Return the number of bytes in this buffer.

const SharedBuffer* alp::SharedBuffer::Pool  )  const
 

Place the shared buffer into the process's buffer pool.

If a buffer of this data doesn't already exist in the pool, this buffer is modified and placed in the pool. Otherwise, your reference on this buffer is released, a reference on the on in the pool added and that buffer returned to you.

int32_t alp::SharedBuffer::Users  )  const [inline]
 

Return the number of users this buffer has.

Note:
Because of threading issues, you can only safely use this value to check if the user count is 1 or greater than 1; and if it is greater than one, you can't assume it will stay that way.


The documentation for this class was generated from the following file:
Generated on Sat Dec 16 20:29:50 2006 for hiker-0.9 by  doxygen 1.4.4