SLightAtom Class Reference
[Utility Classes and Functions]

#include <support/Atom.h>

Inheritance diagram for SLightAtom:

Detailed Description

A variation of SAtom that only supports strong reference counts.

This can be useful when you want to avoid the overhead of the more complex / richer SAtom class. This class only requires 8 bytes of overhead (the reference count + vtable) in addition to the normal malloc overhead, as opposed to the 24 bytes required by SAtom. Reference count management is also slightly more efficient, since there is only one reference count to maintain.

You will often not use virtual inheritance with this class, since it is usually used to manage internal data structures where you don't have to worry about someone else wanting to mix together two different reference-counted classes.

Const Reference Counting

These are for debugging. We use them to identify const vs. non-const references, which can be used to do sanity checks.

int32_t ConstCount () const

int32_t DecStrong (const void *id)

void DecStrongFast ()

int32_t IncStrong (const void *id)

void IncStrongFast ()

Reference Counting

Basic APIs for managing the reference count of an SLightAtom object.

int32_t DecStrong (const void *id) const

Decrement the atom's strong pointer count.

void DecStrongFast () const

Optimized version of DecStrong() for release builds.

int32_t IncStrong (const void *id) const

Increment the atom's strong pointer count.

void IncStrongFast () const

Optimized version of IncStrong() for release builds.

Reference Count Owner

SAtom provides a rich reference count debugging facility described in SAtom Debugging. For it to work, each reference on an SLightAtom must have a unique object ID (usually a memory address) of the entity that "owns" that reference. You should use these APIs in situations where that object ID changes, so that when atom debugging is enabled others will be able to properly track their references.

bool HasManyStrongPointers () const

Return true if this atom has more than one strong acquire on it.

void RenameOwnerID (const void *newID, const void *oldID) const

Change an owner ID associated with this atom.

static void MovePointersAfter (SLightAtom **newPtr, SLightAtom **oldPtr, size_t num=1)

Perform a memmove() of an array of SLightAtom*, updating owner IDs as needed.

static void MovePointersBefore (SLightAtom **newPtr, SLightAtom **oldPtr, size_t num=1)

Perform a memcpy() of an array of SLightAtom*, updating owner IDs as needed.

Debugging

These methods allow you to work with the SLightAtom reference count debugging and leak tracking mechanism as described in SAtom Debugging. They are only implemented on debug builds when the atom debugging facility is enabled. In other cases, they are a no-op.
Also see the SAtom debugging functions for more features (SAtom and SLightAtom share the same back-end debugging state).

void Report (const sptr< ITextOutput > &io, uint32_t flags=0) const

Print information state and references on this atom to io.

int32_t StrongCount () const

Return the number of strong/weak pointers currently on the atom.

static bool ExistsAndIncStrong (SLightAtom *atom)

Check for atom existance and acquire strong reference.

Bookkeeping

Object initialization, destruction, and lifetime management.

virtual void InitAtom ()

Called the first time a strong reference is acquired. All significant object initialization should go here.

SLightAtom ()

Construct a new SAtom.

virtual ~SLightAtom ()

Destructor called when it is time to destroy the object. Never call yourself!

Friends

class SAtomTracker

Constructor & Destructor Documentation

SLightAtom ( ) [protected]

Construct a new SAtom.
The reference counts start out at zero. You must call IncStrong() (or create a sptr<T> to the SLightAtom) to acquire the first reference, at which point InitAtom() will be called.

~SLightAtom ( ) [protected, virtual]

Destructor called when it is time to destroy the object. Never call yourself!

Member Function Documentation

int32_t ConstCount ( ) const

int32_t DecStrong ( const void * id )

int32_t DecStrong ( const void * id ) const

Decrement the atom's strong pointer count.

void DecStrongFast ( )

void DecStrongFast ( ) const

Optimized version of DecStrong() for release builds.

bool ExistsAndIncStrong ( SLightAtom * atom ) [static]

Check for atom existance and acquire strong reference.
Check whether the given atom currently exists, and acquire a strong pointer if so. This only works when the leak checker is turned on; otherwise, false is always returned.
Note:
Debugging only. Set the ATOM_DEBUG and ATOM_REPORT environment variables to use.

See also:
Report()
MarkLeakReport()

bool HasManyStrongPointers ( ) const

Return true if this atom has more than one strong acquire on it.

Note:
Be careful how you use this information. You must already hold a strong pointer on the atom, and even then it can change from "true" to "false" before you get the result.

int32_t IncStrong ( const void * id )

int32_t IncStrong ( const void * id ) const

Increment the atom's strong pointer count.
This is the standard reference count -- once it transitions to zero, the atom will become invalid. An atom starts with a reference count of zero, and gets invalidated the first time it transitions from one to zero. The optional id parameter is the memory address of the object holding this reference. It is only used for debugging.
The first time you call IncStrong() will result in InitAtom() being called.

See also:
sptr<>

void IncStrongFast ( )

void IncStrongFast ( ) const

Optimized version of IncStrong() for release builds.

void InitAtom ( ) [protected, virtual]

Called the first time a strong reference is acquired. All significant object initialization should go here.
You can override it and do any setup you need. Note that you do not need to call the SLightAtom implementation. (So you can derive from two different SLightAtom implementations and safely call down to both of their IncStrong() methods.)
See also:
IncStrong()

void MovePointersAfter ( SLightAtom ** newPtr,

SLightAtom ** oldPtr,

size_t num = 1

) [static]

Perform a memmove() of an array of SLightAtom*, updating owner IDs as needed.

void MovePointersBefore ( SLightAtom ** newPtr,

SLightAtom ** oldPtr,

size_t num = 1

) [static]

Perform a memcpy() of an array of SLightAtom*, updating owner IDs as needed.

void RenameOwnerID ( const void * newID,

const void * oldID

) const

Change an owner ID associated with this atom.
This is useful, for example, if you have a piece of memory with a pointer to an atom, whose memory address you have used for the reference ID. If you are moving your memory to a new location with memcpy(), you can use this function to change the ID stored in the atom for your reference.
This function does nothing if atom debugging is not currently enabled.

See also:
MovePointersBefore(), MovePointersAfter()

void Report ( const sptr< ITextOutput > & io,

uint32_t flags = 0

) const

Print information state and references on this atom to io.
The flags may be one of B_ATOM_REPORT_FORCE_LONG, B_ATOM_REPORT_FORCE_SHORT, or B_ATOM_REPORT_FORCE_SUMMARY, as well as B_ATOM_REPORT_REMOVE_HEADER.
This is the API called by the "atom report" command described in SAtom Debugging.

Note:
Debugging only. Set the ATOM_DEBUG and ATOM_REPORT environment variables to use.
This function only works if you are linking with a library that contains debugging code and have set the ATOM_DEBUG environment variable. Choices for ATOM_DEBUG are:

<= 0: Debugging disabled.
<= 5: Simple debugging -- create/delete statistics only.
<= 10: Full SAtom debugging enabled.

In addition, you can modify the default Report() format with the ATOM_REPORT environment variable:

<= 0: Short summary report.
<= 5: One-line call stacks.
<= 10: Call stacks with full symbols.

int32_t StrongCount ( ) const

Return the number of strong/weak pointers currently on the atom.

Note:
Debugging only. The returned value is no longer valid as soon as you receive it.

Friends And Related Function Documentation

friend class SAtomTracker [friend]

The documentation for this class was generated from the following files:


Const Reference Counting
These are for debugging. We use them to identify const vs. non-const references, which can be used to do sanity checks.
int32_t	ConstCount () const
int32_t	DecStrong (const void *id)
void	DecStrongFast ()
int32_t	IncStrong (const void *id)
void	IncStrongFast ()
Reference Counting
Basic APIs for managing the reference count of an SLightAtom object.
int32_t	DecStrong (const void *id) const
	Decrement the atom's strong pointer count.
void	DecStrongFast () const
	Optimized version of DecStrong() for release builds.
int32_t	IncStrong (const void *id) const
	Increment the atom's strong pointer count.
void	IncStrongFast () const
	Optimized version of IncStrong() for release builds.
Reference Count Owner
SAtom provides a rich reference count debugging facility described in SAtom Debugging. For it to work, each reference on an SLightAtom must have a unique object ID (usually a memory address) of the entity that "owns" that reference. You should use these APIs in situations where that object ID changes, so that when atom debugging is enabled others will be able to properly track their references.
bool	HasManyStrongPointers () const
	Return true if this atom has more than one strong acquire on it.
void	RenameOwnerID (const void newID, const void oldID) const
	Change an owner ID associated with this atom.
static void	MovePointersAfter (SLightAtom newPtr, SLightAtom oldPtr, size_t num=1)
	Perform a memmove() of an array of SLightAtom*, updating owner IDs as needed.
static void	MovePointersBefore (SLightAtom newPtr, SLightAtom oldPtr, size_t num=1)
	Perform a memcpy() of an array of SLightAtom*, updating owner IDs as needed.
Debugging
These methods allow you to work with the SLightAtom reference count debugging and leak tracking mechanism as described in SAtom Debugging. They are only implemented on debug builds when the atom debugging facility is enabled. In other cases, they are a no-op. Also see the SAtom debugging functions for more features (SAtom and SLightAtom share the same back-end debugging state).
void	Report (const sptr< ITextOutput > &io, uint32_t flags=0) const
	Print information state and references on this atom to io.
int32_t	StrongCount () const
	Return the number of strong/weak pointers currently on the atom.
static bool	ExistsAndIncStrong (SLightAtom *atom)
	Check for atom existance and acquire strong reference.
Bookkeeping
Object initialization, destruction, and lifetime management.
virtual void	InitAtom ()
	Called the first time a strong reference is acquired. All significant object initialization should go here.
	SLightAtom ()
	Construct a new SAtom.
virtual	~SLightAtom ()
	Destructor called when it is time to destroy the object. Never call yourself!
Friends
class	SAtomTracker

SLightAtom Class Reference [Utility Classes and Functions]

Detailed Description

Const Reference Counting

Reference Counting

Reference Count Owner

Debugging

Bookkeeping

Friends

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

SLightAtom Class Reference
[Utility Classes and Functions]