Citizen is a class that should be among all LSST classes base classes, and handles basic memory management. More...

#include <Citizen.h>

Inheritance diagram for lsst::daf::base::Citizen:

Public Types
enum	{ magicSentinel = 0xdeadbeef }

typedef unsigned long	memId
	Type of the block's ID. More...

typedef memId(*	memNewCallback )(const memId cid)
	A function used to register a callback. More...

typedef memId(*	memCallback )(const Citizen *ptr)

Public Member Functions
	Citizen (const std::type_info &)

	Citizen (Citizen const &)

	~Citizen ()

Citizen &	operator= (Citizen const &)

std::string	repr () const
	Return a string representation of a Citizen. More...

void	markPersistent (void)
	Mark a Citizen as persistent and not destroyed until process end. More...

memId	getId () const
	Return the Citizen's ID. More...

Static Public Member Functions
static bool	hasBeenCorrupted ()
	Check all allocated blocks for corruption. More...

static memId	getNextMemId ()
	Return the memId of the next object to be allocated. More...

static int	init ()
	Called once when the memory system is being initialised. More...

Census
Provide a list of current Citizens
static int	census (int, memId startingMemId=0)
	How many active Citizens are there? More...

static void	census (std::ostream &stream, memId startingMemId=0)
	Print a list of all active Citizens to stream, sorted by ID. More...

static const std::vector < const Citizen * > *	census ()
	Return a (newly allocated) std::vector of active Citizens sorted by ID. More...

callbackIDs
Set callback Ids. The old Id is returned
static memId	setNewCallbackId (memId id)
	Call the NewCallback when block is allocated. More...

static memId	setDeleteCallbackId (memId id)
	Call the current DeleteCallback when block is deleted. More...

Private Types
typedef std::pair< memId, pthread_t >	CitizenInfo

typedef std::map< Citizen const *, CitizenInfo >	table

Private Member Functions
bool	_hasBeenCorrupted () const

Static Private Member Functions
static memId	_addCitizen (Citizen const *c)

static memId	_nextMemIdAndIncrement (void)
	Return the memId and prepare for the next object to be allocated. More...

static memId	_nextMemId (void)
	Return the memId of the next object to be allocated. More...

Private Attributes
int	_sentinel

memId	_CitizenId

const char *	_typeName

Static Private Attributes
static table	_activeCitizens

static table	_persistentCitizens

static memId	_newId = 0

static memId	_deleteId = 0

static memNewCallback	_newCallback = defaultNewCallback

static memCallback	_deleteCallback = defaultDeleteCallback

static memCallback	_corruptionCallback = defaultCorruptionCallback

Friends
class	PersistentCitizenScope

callbacks
Set the New/Delete callback functions; in each case the previously installed callback is returned. These callback functions return a value which is Added to the previously registered id. The default callback functions are called default{New,Delete}Callback; you may want to set a break point in these callbacks from your favourite debugger
static memNewCallback	setNewCallback (memNewCallback func)
	Set the NewCallback function. More...

static memCallback	setDeleteCallback (memCallback func)
	Set the DeleteCallback function. More...

static memCallback	setCorruptionCallback (memCallback func)
	Set the CorruptionCallback function. More...

static bool &	_shouldPersistCitizens ()
	Set the NewCallback function. More...

Detailed Description

Citizen is a class that should be among all LSST classes base classes, and handles basic memory management.

Instances of subclasses of Citizen will automatically be given a unique id.

You can ask for infomation about the currently allocated Citizens using the census functions, request that a function of your choice be called when a specific block ID is allocated or deleted, and check whether any of the data blocks are known to be corrupted

Definition at line 56 of file Citizen.h.

Member Typedef Documentation

typedef std::pair<memId, pthread_t> lsst::daf::base::Citizen::CitizenInfo

private

Definition at line 92 of file Citizen.h.

typedef memId(* lsst::daf::base::Citizen::memCallback)(const Citizen *ptr)

Definition at line 62 of file Citizen.h.

typedef unsigned long lsst::daf::base::Citizen::memId

Type of the block's ID.

Definition at line 59 of file Citizen.h.

typedef memId(* lsst::daf::base::Citizen::memNewCallback)(const memId cid)

A function used to register a callback.

Definition at line 61 of file Citizen.h.

typedef std::map<Citizen const*, CitizenInfo> lsst::daf::base::Citizen::table

private

Definition at line 93 of file Citizen.h.

Member Enumeration Documentation

anonymous enum

Enumerator
magicSentinel

Definition at line 89 of file Citizen.h.

89 { magicSentinel = 0xdeadbeef };

lsst::daf::base::Citizen::magicSentinel

Definition: Citizen.h:89

Constructor & Destructor Documentation

lsst::daf::base::Citizen::Citizen ( const std::type_info & type )

Definition at line 173 of file Citizen.cc.

                                                 :
     _sentinel(magicSentinel),
     _CitizenId(_addCitizen(this)),
     _typeName(type.name()) {
 }

lsst::daf::base::Citizen::Citizen ( Citizen const & citizen )

Definition at line 179 of file Citizen.cc.

                                               :
     _sentinel(magicSentinel),
     _CitizenId(_addCitizen(this)),
     _typeName(citizen._typeName) {
 }

lsst::daf::base::Citizen::~Citizen ( )

Definition at line 185 of file Citizen.cc.

                          {
     {
         WriteGuard guard(citizenLock);
         if (_CitizenId == _deleteId) {
             _deleteId += _deleteCallback(this);
         }
     }
 
     (void)_hasBeenCorrupted();  // may execute callback
     _sentinel = 0x0000dead;     // In case we have a dangling pointer
 
     bool corrupt = false;
     {
         WriteGuard guard(citizenLock);
         size_t nActive = _activeCitizens.erase(this);
         corrupt = nActive > 1 ||
             (nActive == 0 && _persistentCitizens.erase(this) != 1);
     }
     if (corrupt) {
         (void)_corruptionCallback(this);
     }
 }

Member Function Documentation

dafBase::Citizen::memId lsst::daf::base::Citizen::_addCitizen ( Citizen const * c )

staticprivate

Definition at line 159 of file Citizen.cc.

                                                                 {
     memId cid = _nextMemIdAndIncrement();
     WriteGuard guard(citizenLock);
     if (_shouldPersistCitizens()) {
         _persistentCitizens[c] = std::make_pair(cid, pthread_self());
     } else {
         _activeCitizens[c] = std::make_pair(cid, pthread_self());
     }
     if (cid == _newId) {
         _newId += _newCallback(cid);
     }
     return cid;
 }

bool lsst::daf::base::Citizen::_hasBeenCorrupted ( ) const

private

Check for corruption Return true if the block is corrupted, but only after calling the corruptionCallback

Definition at line 342 of file Citizen.cc.

                                              {
     if (_sentinel == static_cast<int>(magicSentinel)) {
         return false;
     }
 
     (void)_corruptionCallback(this);
     return true;
 }

dafBase::Citizen::memId lsst::daf::base::Citizen::_nextMemId ( void )

staticprivate

Return the memId of the next object to be allocated.

Definition at line 233 of file Citizen.cc.

                                                {
     return perThreadId.getRef();
 }

dafBase::Citizen::memId lsst::daf::base::Citizen::_nextMemIdAndIncrement ( void )

staticprivate

Return the memId and prepare for the next object to be allocated.

Definition at line 238 of file Citizen.cc.

                                                            {
     return perThreadId.getRef()++;
 }

bool & lsst::daf::base::Citizen::_shouldPersistCitizens ( void )

staticprivate

Set the NewCallback function.

Definition at line 473 of file Citizen.cc.

                                                  {
     return perThreadPersistFlag.getRef();
 }

int lsst::daf::base::Citizen::census	(	int	,
		memId	startingMemId = `0`
	)

static

How many active Citizens are there?

Parameters

startingMemId Don't print Citizens with lower IDs

Definition at line 266 of file Citizen.cc.

       {
     if (startingMemId == 0) {              // easy
         ReadGuard guard(citizenLock);
         return _activeCitizens.size();
     }
 
     int n = 0;
     ReadGuard guard(citizenLock);
     for (table::iterator cur = _activeCitizens.begin();
          cur != _activeCitizens.end(); cur++) {
         if (cur->first->_CitizenId >= startingMemId) {
             n++;
         }
     }
 
     return n;    
 }

void lsst::daf::base::Citizen::census	(	std::ostream &	stream,
		memId	startingMemId = `0`
	)

static

Print a list of all active Citizens to stream, sorted by ID.

Parameters

stream	stream to print to
startingMemId	Don't print Citizens with lower IDs

Definition at line 289 of file Citizen.cc.

       {
     ReadGuard guard(citizenLock);
 
     boost::scoped_ptr<std::vector<Citizen const*> const> leaks(Citizen::census());
 
     for (std::vector<Citizen const *>::const_iterator citizen = leaks->begin(), end = leaks->end();
          citizen != end; ++citizen) {
         if ((*citizen)->getId() >= startingMemId) {
             stream << (*citizen)->repr() << "\n";
         }
     }
 }

std::vector< dafBase::Citizen const * > const * lsst::daf::base::Citizen::census ( )

static

Return a (newly allocated) std::vector of active Citizens sorted by ID.

You are responsible for deleting it; or you can say boost::scoped_ptr<std::vector<Citizen const*> const> leaks(Citizen::census()); and not bother (that becomes std::unique_ptr in C++11)

Definition at line 321 of file Citizen.cc.

                                                                {
     std::vector<Citizen const*>* vec =
         new std::vector<Citizen const*>(0);
     ReadGuard guard(citizenLock);
     vec->reserve(_activeCitizens.size());
 
     for (table::iterator cur = _activeCitizens.begin();
          cur != _activeCitizens.end(); cur++) {
         vec->push_back(dynamic_cast<Citizen const*>(cur->first));
     }
         
     std::sort(vec->begin(), vec->end(), cmpId);
 
     return vec;
 }

dafBase::Citizen::memId lsst::daf::base::Citizen::getId ( ) const

Return the Citizen's ID.

Definition at line 223 of file Citizen.cc.

                                                 {
     return _CitizenId;
 }

dafBase::Citizen::memId lsst::daf::base::Citizen::getNextMemId ( )

static

Return the memId of the next object to be allocated.

Definition at line 228 of file Citizen.cc.

                                                  {
     return _nextMemId();
 }

bool lsst::daf::base::Citizen::hasBeenCorrupted ( )

static

Check all allocated blocks for corruption.

Definition at line 352 of file Citizen.cc.

                                       {
     ReadGuard guard(citizenLock);
     for (table::iterator cur = _activeCitizens.begin();
          cur != _activeCitizens.end(); cur++) {
         if (cur->first->_hasBeenCorrupted()) {
             return true;
         }
     }
     for (table::iterator cur = _persistentCitizens.begin();
          cur != _persistentCitizens.end(); cur++) {
         if (cur->first->_hasBeenCorrupted()) {
             return true;
         }
     }
 
     return false;
 }

int lsst::daf::base::Citizen::init ( )

static

Called once when the memory system is being initialised.

Definition at line 213 of file Citizen.cc.

                          {
     volatile int dummy = 1;
     return dummy;
 }

void lsst::daf::base::Citizen::markPersistent ( void )

Mark a Citizen as persistent and not destroyed until process end.

Definition at line 253 of file Citizen.cc.

                                         {
     WriteGuard guard(citizenLock);
     _persistentCitizens[this] = _activeCitizens[this];
     _activeCitizens.erase(this);
 }

Citizen& lsst::daf::base::Citizen::operator= ( Citizen const & )

inline

Definition at line 68 of file Citizen.h.

68 { return *this; }

std::string lsst::daf::base::Citizen::repr ( ) const

Return a string representation of a Citizen.

Definition at line 244 of file Citizen.cc.

                                      {
     return boost::str(boost::format("%d: %08x %s")
                       % _CitizenId
                       % this
                       % lsst::utils::demangleType(_typeName)
                      );
 }

dafBase::Citizen::memCallback lsst::daf::base::Citizen::setCorruptionCallback ( Citizen::memCallback func )

static

Set the CorruptionCallback function.

Parameters

func	function be called when block is found to be corrupted

Definition at line 431 of file Citizen.cc.

                                                      {
     Citizen::memCallback old = _corruptionCallback;
     _corruptionCallback = func;
 
     return old;
 }

dafBase::Citizen::memCallback lsst::daf::base::Citizen::setDeleteCallback ( Citizen::memCallback func )

static

Set the DeleteCallback function.

Parameters

func	function be called when desired block is deleted

Definition at line 421 of file Citizen.cc.

       {
     Citizen::memCallback old = _deleteCallback;
     _deleteCallback = func;
 
     return old;
 }

dafBase::Citizen::memId lsst::daf::base::Citizen::setDeleteCallbackId ( Citizen::memId id )

static

Call the current DeleteCallback when block is deleted.

Parameters

id	Desired ID

Definition at line 386 of file Citizen.cc.

       {
     WriteGuard guard(citizenLock);
     Citizen::memId oldId = _deleteId;
     _deleteId = id;
 
     return oldId;
 }

dafBase::Citizen::memNewCallback lsst::daf::base::Citizen::setNewCallback ( Citizen::memNewCallback func )

static

Set the NewCallback function.

Parameters

func	The new function to be called when a designated block is allocated

Definition at line 411 of file Citizen.cc.

       {
     Citizen::memNewCallback old = _newCallback;
     _newCallback = func;
 
     return old;
 }

dafBase::Citizen::memId lsst::daf::base::Citizen::setNewCallbackId ( Citizen::memId id )

static

Call the NewCallback when block is allocated.

Parameters

id	Desired ID

Definition at line 375 of file Citizen.cc.

       {
     WriteGuard guard(citizenLock);
     Citizen::memId oldId = _newId;
     _newId = id;
 
     return oldId;
 }

Friends And Related Function Documentation

friend class PersistentCitizenScope

friend

Definition at line 120 of file Citizen.h.

Member Data Documentation

dafBase::Citizen::table lsst::daf::base::Citizen::_activeCitizens

staticprivate

Definition at line 105 of file Citizen.h.

memId lsst::daf::base::Citizen::_CitizenId

private

Definition at line 96 of file Citizen.h.

dafBase::Citizen::memCallback lsst::daf::base::Citizen::_corruptionCallback = defaultCorruptionCallback

staticprivate

Definition at line 116 of file Citizen.h.

dafBase::Citizen::memCallback lsst::daf::base::Citizen::_deleteCallback = defaultDeleteCallback

staticprivate

Definition at line 115 of file Citizen.h.

dafBase::Citizen::memId lsst::daf::base::Citizen::_deleteId = 0

staticprivate

Definition at line 112 of file Citizen.h.

dafBase::Citizen::memNewCallback lsst::daf::base::Citizen::_newCallback = defaultNewCallback

staticprivate

Definition at line 114 of file Citizen.h.

dafBase::Citizen::memId lsst::daf::base::Citizen::_newId = 0

staticprivate

Definition at line 111 of file Citizen.h.

dafBase::Citizen::table lsst::daf::base::Citizen::_persistentCitizens

staticprivate

Definition at line 106 of file Citizen.h.

int lsst::daf::base::Citizen::_sentinel

private

Definition at line 95 of file Citizen.h.

const char* lsst::daf::base::Citizen::_typeName

private

Definition at line 97 of file Citizen.h.

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

/home/lsstsw/stack/Linux64/daf_base/11.0.rc2+6/include/lsst/daf/base/Citizen.h
/home/lsstsw/stack/Linux64/daf_base/11.0.rc2+6/src/Citizen.cc

Public Types

Public Member Functions

Static Public Member Functions

Private Types

Private Member Functions

Static Private Member Functions

Private Attributes

Static Private Attributes

Friends

callbacks

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation