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;

Rose::Callbacks::List

List of callback functors.

Definition callbacks.h:83

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 83 of file callbacks.h.

#include <roseSupport/callbacks.h>

Inheritance diagram for Rose::Callbacks::List< T >:

[legend]

Public Types
typedef T	CallbackType
	Functor class.

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

Public Member Functions
	List (const List &other)

	List (CallbackType *callback)

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

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

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

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

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

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

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

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

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

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

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

Member Typedef Documentation

◆ CallbackType

template<class T >

typedef T Rose::Callbacks::List< T >::CallbackType

Functor class.

Definition at line 85 of file callbacks.h.

◆ CBList

template<class T >

typedef std::list<CallbackType*> Rose::Callbacks::List< T >::CBList

Standard vector of functor pointers.

Definition at line 86 of file callbacks.h.

Constructor & Destructor Documentation

◆ List() [1/3]

template<class T >

Rose::Callbacks::List< T >::List ( )

inline

Definition at line 93 of file callbacks.h.

◆ List() [2/3]

template<class T >

Rose::Callbacks::List< T >::List ( const List< T > & other )

inline

Definition at line 95 of file callbacks.h.

◆ List() [3/3]

template<class T >

Rose::Callbacks::List< T >::List ( CallbackType * callback )

inlineexplicit

Definition at line 100 of file callbacks.h.

Member Function Documentation

◆ size()

template<class T >

size_t Rose::Callbacks::List< T >::size ( ) const

inline

Returns the number of callbacks in the list.

Thread safety: This method is thread safe.

Definition at line 107 of file callbacks.h.

◆ empty()

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 117 of file callbacks.h.

◆ append()

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 128 of file callbacks.h.

◆ prepend()

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 141 of file callbacks.h.

◆ after()

template<class T >

List & Rose::Callbacks::List< T >::after	(	CallbackType *	relative_to,
		CallbackType *	cb,
		size_t	nreplacements = `UNLIMITED`
	)

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 155 of file callbacks.h.

◆ before()

template<class T >

List & Rose::Callbacks::List< T >::before	(	CallbackType *	relative_to,
		CallbackType *	cb,
		size_t	nreplacements = `UNLIMITED`
	)

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 172 of file callbacks.h.

◆ replace()

template<class T >

List & Rose::Callbacks::List< T >::replace	(	CallbackType *	old_cb,
		CallbackType *	new_cb,
		size_t	nreplacements = `UNLIMITED`,
		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 193 of file callbacks.h.

References Rose::Callbacks::FORWARD.

◆ erase()

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 221 of file callbacks.h.

References Rose::Callbacks::FORWARD.

◆ clear()

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 245 of file callbacks.h.

◆ callbacks()

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 254 of file callbacks.h.

Referenced by Rose::Callbacks::List< T >::apply().

◆ 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 272 of file callbacks.h.

References Rose::Callbacks::List< T >::callbacks(), and Rose::Callbacks::FORWARD.

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

callbacks.h

Description

Example Usage

Public Types

Public Member Functions

Member Typedef Documentation

◆ CallbackType

◆ CBList

Constructor & Destructor Documentation

◆ List() [1/3]

◆ List() [2/3]

◆ List() [3/3]

Member Function Documentation

◆ size()

◆ empty()

◆ append()

◆ prepend()

◆ after()

◆ before()

◆ replace()

◆ erase()

◆ clear()

◆ callbacks()

◆ apply()