ROSE  0.11.145.0
Public Types | Public Member Functions | List of all members
Rose::Callbacks::List< T > Class Template Reference

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) {}
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.

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

#include <roseSupport/callbacks.h>

Inheritance diagram for Rose::Callbacks::List< T >:
Inheritance graph
[legend]

Public Types

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

Public Member Functions

 List (const List &other)
 
 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...
 
Listappend (CallbackType *cb)
 Append a functor to the end of the list without copying it. More...
 
Listprepend (CallbackType *cb)
 Prepend callback to beginning of list without copying it. More...
 
Listafter (CallbackType *relative_to, CallbackType *cb, size_t nreplacements=UNLIMITED)
 Insert a callback after another. More...
 
Listbefore (CallbackType *relative_to, CallbackType *cb, size_t nreplacements=UNLIMITED)
 Insert a callback before another. More...
 
Listreplace (CallbackType *old_cb, CallbackType *new_cb, size_t nreplacements=UNLIMITED, 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...
 
Listclear ()
 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...
 

Member Typedef Documentation

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

Functor class.

Definition at line 84 of file callbacks.h.

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

Standard vector of functor pointers.

Definition at line 85 of file callbacks.h.

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

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

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

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

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

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

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

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

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

Referenced by Rose::BinaryAnalysis::AsmUnparser::CallbackLists::clear().

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

Referenced by Rose::Callbacks::List< Rose::BinaryAnalysis::AsmUnparser::UnparserCallback >::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 271 of file callbacks.h.


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