SSharedBuffer Class Reference
[Utility Classes and Functions]

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

SSharedBuffer * BeginBuffering ()

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.

SSharedBuffer * Edit () const

Edit() without changing size.

SSharedBuffer * Edit (size_t newLength) const

Given a read-only buffer, start modifying it.

SSharedBuffer * EndBuffering ()

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 SSharedBuffer * Pool () 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 SSharedBuffer * Alloc (size_t length)

Create a new buffer of the given size.

static const SSharedBuffer * BufferFromData (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:


Public Types
typedef void(*	dec_ref_func )()
typedef void(*	inc_ref_func )()
Public Member Functions
SSharedBuffer *	BeginBuffering ()
	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.
SSharedBuffer *	Edit () const
	Edit() without changing size.
SSharedBuffer *	Edit (size_t newLength) const
	Given a read-only buffer, start modifying it.
SSharedBuffer *	EndBuffering ()
	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 SSharedBuffer *	Pool () 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 SSharedBuffer *	Alloc (size_t length)
	Create a new buffer of the given size.
static const SSharedBuffer *	BufferFromData (const void *data)
	Inverse of Data().

SSharedBuffer Class Reference [Utility Classes and Functions]

Detailed Description

Public Types

Public Member Functions

Static Public Member Functions

Member Typedef Documentation

Member Function Documentation

SSharedBuffer Class Reference
[Utility Classes and Functions]