List of callback functors. More...

#include <callbacks.h>

Collaboration diagram for ROSE_Callbacks::List< T >:

Public Types
typedef T	CallbackType
	Functor class. More...

typedef std::list< CallbackType * >	CBList
	Standard vector of functor pointers. More...

Public Member Functions
	List ()

	List (CallbackType *callback)

size_t	size () const
	Returns the number of callbacks in the list. More...

bool	empty () const
	Predicate to test whether the list is empty. More...

List &	append (CallbackType *cb)
	Append a functor to the end of the list without copying it. More...

List &	prepend (CallbackType *cb)
	Prepend callback to beginning of list without copying it. More...

List &	after (CallbackType relative_to, CallbackType cb, size_t nreplacements=(size_t)(-1))
	Insert a callback after another. More...

List &	before (CallbackType relative_to, CallbackType cb, size_t nreplacements=(size_t)(-1))
	Insert a callback before another. More...

List &	replace (CallbackType old_cb, CallbackType new_cb, size_t nreplacements=(size_t)(-1), Direction dir=FORWARD)
	Replace one callback with another. More...

bool	erase (CallbackType *cb, Direction dir=FORWARD)
	Remove a callback from a list without destroying it. More...

List &	clear ()
	Remove all callbacks from list without destroying them. More...

std::list< CallbackType * >	callbacks () const
	Returns a copy of the underlying STL vector of functors. More...

template<class ArgumentType >
bool	apply (bool b, const ArgumentType &args, Direction dir=FORWARD) const
	Invokes all functors in the callback list. More...

Private Attributes
RTS_mutex_t	mutex

CBList	list

Detailed Description

template<class T>
class ROSE_Callbacks::List< T >

List of callback functors.

This template defines ordered containers of callback functors and thread-safe functions for accessing the containers.

Example Usage

The first step is to create a functor class having one or more callbacks (operator() methods), each of which takes a struct reference containing the data to which the callback is applied.

class MyCallback: public MyCallbackBase { //base class optional
public:
    MyCallback(): ncalls(0) {}
    // Callback argument structure.  Data members can be anything
    // you want, and you can even have more than one of these
    // structs--one per callback signature.  The constructor
    // should generally just assign arguments to data members.
    struct Args {
        Args(SgAsmInstruction *insn, int callno, char *name):
            insn(insn), callno(callno), name(name) {}
        SgAsmInstruction *insn;
        int callno;
        char *name;
    };
    // The callback.  You can overload these, but they'll all
    // take two arguments where the first is a Boolean and the
    // second is one of the argument types you defined above.
    bool operator()(bool b, const Args &args) {
        ncalls++;
        printf(stderr,"%s: %d\n", args.name, args.callno);
        insns.push_back(args.insn);
        return b;
    }
    // Some data members accessible by the callback(s)
    size_t ncalls;
    static std::vector<SgAsmInstruction*> insns;
};

The second step is to create a list to hold these callbacks. Our example callback was derived from a base class, so we'll use that base class as the list element type.

typedef ROSE_Callbacks::List<MyCallbackBase> MyCallbackList;

MyCallbackList cbl;

Add some callbacks to the list. We'll just add one for this example.

cbl.append(new MyCallback);

Finally, invoke all the callbacks in the list, supplying some arguments that will be used for each callback.

bool result = cbl.apply(true, MyCallback::Args(insn, 5, "foo"));

Definition at line 79 of file callbacks.h.

Member Typedef Documentation

template<class T >

typedef T ROSE_Callbacks::List< T >::CallbackType

Functor class.

Definition at line 81 of file callbacks.h.

template<class T >

typedef std::list<CallbackType*> ROSE_Callbacks::List< T >::CBList

Standard vector of functor pointers.

Definition at line 82 of file callbacks.h.

Constructor & Destructor Documentation

template<class T >

ROSE_Callbacks::List< T >::List ( )

inline

Definition at line 84 of file callbacks.h.

References RTS_LAYER_ROSE_CALLBACKS_LIST_OBJ, and RTS_mutex_init().

template<class T >

ROSE_Callbacks::List< T >::List ( CallbackType * callback)

inlineexplicit

Definition at line 88 of file callbacks.h.

References ROSE_Callbacks::List< T >::append(), RTS_LAYER_ROSE_CALLBACKS_LIST_OBJ, and RTS_mutex_init().

Member Function Documentation

template<class T >

size_t ROSE_Callbacks::List< T >::size ( void ) const

inline

Returns the number of callbacks in the list.

Thread safety: This method is thread safe.

Definition at line 96 of file callbacks.h.

References ROSE_Callbacks::List< T >::list, RTS_MUTEX, and RTS_MUTEX_END.

template<class T >

bool ROSE_Callbacks::List< T >::empty ( ) const

inline

Predicate to test whether the list is empty.

Returns true if the list is empty, false otherwise.

Thread safety: This method is thread safe.

Definition at line 107 of file callbacks.h.

References ROSE_Callbacks::List< T >::list, RTS_MUTEX, and RTS_MUTEX_END.

Referenced by Partitioner::scan_interfunc_bytes(), Partitioner::scan_interfunc_insns(), Partitioner::scan_intrafunc_bytes(), Partitioner::scan_intrafunc_insns(), Partitioner::scan_unassigned_bytes(), and Partitioner::scan_unassigned_insns().

template<class T >

List& ROSE_Callbacks::List< T >::append ( CallbackType * cb)

inline

Append a functor to the end of the list without copying it.

Functors can be inserted more than once into a list, and each occurrence will be called by the apply() method.

Thread safety: This method is thread safe. In fact, it is safe to modify the list while apply() is calling the functors on that list.

Definition at line 120 of file callbacks.h.

References ROSE_Callbacks::List< T >::list, RTS_MUTEX, and RTS_MUTEX_END.

Referenced by ROSE_Callbacks::List< T >::List().

template<class T >

List& ROSE_Callbacks::List< T >::prepend ( CallbackType * cb)

inline

Prepend callback to beginning of list without copying it.

Functors can be inserted more than once into a list, and each occurrence will be called by the apply() method.

Thread safety: This method is thread safe. In fact, it is safe to modify the list while apply() is calling the functors on that list.

Definition at line 133 of file callbacks.h.

References ROSE_Callbacks::List< T >::list, RTS_MUTEX, and RTS_MUTEX_END.

Referenced by Partitioner::scan_interfunc_bytes(), Partitioner::scan_interfunc_insns(), Partitioner::scan_intrafunc_bytes(), and Partitioner::scan_intrafunc_insns().

template<class T >

List& ROSE_Callbacks::List< T >::after	(	CallbackType *	relative_to,
		CallbackType *	cb,
		size_t	nreplacements = `(size_t)(-1)`
	)

inline

Insert a callback after another.

The callback is inserted after each occurrence of the relative_to callback. Up to nreplacement insertions are made beginning at the front of the list.

Thread safety: This method is thread safe. In fact, it is safe to modify the list while apply() is calling the functors on that list.

Definition at line 146 of file callbacks.h.

References ROSE_Callbacks::List< T >::list, RTS_MUTEX, and RTS_MUTEX_END.

template<class T >

List& ROSE_Callbacks::List< T >::before	(	CallbackType *	relative_to,
		CallbackType *	cb,
		size_t	nreplacements = `(size_t)(-1)`
	)

inline

Insert a callback before another.

The callback is inserted before each occurrence of the relative_to callback. Up to nreplacement insertions are made begin$ning at the front of the list.

Thread safety: This method is thread safe. In fact, it is safe to modify the list while apply() is calling the functors on that list.

Definition at line 164 of file callbacks.h.

References ROSE_Callbacks::List< T >::list, RTS_MUTEX, and RTS_MUTEX_END.

template<class T >

List& ROSE_Callbacks::List< T >::replace	(	CallbackType *	old_cb,
		CallbackType *	new_cb,
		size_t	nreplacements = `(size_t)(-1)`,
		Direction	dir = `FORWARD`
	)

inline

Replace one callback with another.

The replaced callback is removed from the list as if by erase() without deleting it, and its replacement is inserted at the same position without copying it. At most nreplacements are performed (the default is unlimited). Replacements are performed in the direction specified.

Thread safety: This method is thread safe. In fact, it is safe to modify the list while apply() is calling the functors on that list.

Definition at line 184 of file callbacks.h.

References ROSE_Callbacks::FORWARD, ROSE_Callbacks::List< T >::list, RTS_MUTEX, and RTS_MUTEX_END.

template<class T >

bool ROSE_Callbacks::List< T >::erase	(	CallbackType *	cb,
		Direction	dir = `FORWARD`
	)

inline

Remove a callback from a list without destroying it.

The list is traversed in the specified direction and the first functor that matches (by pointer comparison) the specified callback is removed from the list. Returns true if a functor was removed, false otherwise.

Thread safety: This method is thread safe. In fact, it is safe to modify the list while apply() is calling the functors on that list.

Definition at line 212 of file callbacks.h.

References ROSE_Callbacks::FORWARD, ROSE_Callbacks::List< T >::list, RTS_MUTEX, and RTS_MUTEX_END.

template<class T >

List& ROSE_Callbacks::List< T >::clear ( )

inline

Remove all callbacks from list without destroying them.

Thread safety: This method is thread safe. In fact, it is safe to modify the list while apply() is calling the functors on that list.

Definition at line 240 of file callbacks.h.

References ROSE_Callbacks::List< T >::list, RTS_MUTEX, and RTS_MUTEX_END.

template<class T >

std::list<CallbackType*> ROSE_Callbacks::List< T >::callbacks ( ) const

inline

Returns a copy of the underlying STL vector of functors.

Thread safety: This method is thread safe.

Definition at line 250 of file callbacks.h.

References ROSE_Callbacks::List< T >::list, RTS_MUTEX, and RTS_MUTEX_END.

Referenced by ROSE_Callbacks::List< T >::apply().

template<class T >

template<class ArgumentType >

bool ROSE_Callbacks::List< T >::apply	(	bool	b,
		const ArgumentType &	args,
		Direction	dir = `FORWARD`
	)		const

inline

Invokes all functors in the callback list.

The functors are invoked sequentially in the order specified by calling its operator() method. Two arguments are provided: a boolean value, and an additional argument with parameterized type. The boolean argument for the first callback is the b argument of this method; the boolean argument of the subsequent callbacks is the return value of the previous callback; the return value of this method is the return value of the last callback (or the initial value of b if no callbacks were made).

Thread safety: This method is thread safe. If this list is modified by one or more of the functors on this list or by another thread, those changes do not affect which callbacks are made by this invocation of apply(). The callbacks should not assume that any particular mutexes or other thread synchronization resources are held. It is possible for a single callback to be invoked concurrently if two or more threads invoke apply() concurrently.

Definition at line 269 of file callbacks.h.

References ROSE_Callbacks::List< T >::callbacks(), ROSE_Callbacks::FORWARD, and ROSE_Callbacks::List< T >::list.

Referenced by Partitioner::scan_contiguous_insns(), and Partitioner::scan_unassigned_bytes().