SSharedBuffer Class Reference
[Utility Classes and Functions]

#include <support/SharedBuffer.h>

List of all members.


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 SSharedBuffer* 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(* dec_ref_func )()
typedef void(* inc_ref_func )()

Public Member Functions

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

Static Public Member Functions

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


Member Typedef Documentation

typedef void(* dec_ref_func)()
 

typedef void(* inc_ref_func)()
 


Member Function Documentation

SSharedBuffer * 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.

SSharedBuffer * BeginBuffering  ) 
 

Convert this SSharedBuffer 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 SSharedBuffer * BufferFromData const void *  data  )  [inline, static]
 

Inverse of Data().

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

bool Buffering  )  const
 

Is BeginBuffering() mode active?

size_t BufferSize  )  const
 

How big is the actual size of the buffer?

int32_t Compare const SSharedBuffer 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 * 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 * Data  )  const [inline]
 

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

void DecStrong const void *   )  const [inline]
 

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

void DecStrongFast  )  const [inline]
 

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

void DecUsers  )  const
 

Remove a user from the buffer.

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

SSharedBuffer * Edit  )  const
 

Edit() without changing size.

SSharedBuffer * 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.

SSharedBuffer * EndBuffering  ) 
 

Stop buffering mode started with BeginBuffering().

void IncStrong const void *   )  const [inline]
 

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

void IncStrongFast  )  const [inline]
 

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

void IncUsers  )  const
 

Add a user to the buffer.

size_t Length  )  const [inline]
 

Return the number of bytes in this buffer.

const SSharedBuffer * 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 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 files: