Cheetah MatchingHandler Reference

MatchingHandlers are a layer on top of Controllers that provide a degree of synchronization between contexts without requiring as much synchronization as a full send/receive paradigm. They allow you to post handlers to be called when a message comes in matching a particular tag, queues up incoming messages until an appropriate handler is posted, and uses the serialization interface to automatically pack and unpack C++ objects. For a more in depth discussion of the motivation and use of MatchingHandlers, see the Guide.

Constructors and Destructor

MatchingHandler()

The default constructor leaves the MatchingHandler uninitialized. It cannot be used until you give it a controller using the 'controller' member function below.

MatchingHandler(Controller)

Construct with a controller. If the controller is valid the MatchingHandler synchronizes with the corresponding MatchingHandlers in the other contexts and is ready to use.

~MatchingHandler()

Destroy the MatchingHandler. All of the corresponding MatchingHandlers should also get destroyed.

Query Functions

Controller controller() const

Get a copy of the controller for this MatchingHandler.

void controller(Controller)

Change the controller for this MatchingHandler to a new on.

int actions(int fromContext)

Return the current number of actions that are pending for messages arriving from the given other context. If no argument is given, count ALL actions.

int messages(int fromContext)

Return the current number of messages that have arrived from the given other context, but have not yet been given to an action. If no argument is given, count ALL messages.

Send

inline void send(int toContext, int matchingTag)

template<class T1>
inline void send(int to, int tag, const T1&)

template<class T1, class T2>
inline void send(int to, int tag, const T1&, const T2&)

template<class T1, class T2, class T3>
inline void send(int to, int tag, const T1&, const T2&, const T3&)

template<class T1, class T2, class T3, class T4>
inline void send(int to, int tag, const T1&, const T2&, const T3&, const T4&)

Send a message from this context to the given context with the given matching tag and zero, one, two, three or four arguments. The arguments are packed up using the default serializer.

SendWith

template<class SerializeTag>
inline void sendWith(const SerializeTag&, int toContext, int matchingTag)

template<class SerializeTag, class T1>
inline void sendWith(const SerializeTag&, int to, int tag, const T1&)

template<class SerializeTag, class T1, class T2>
inline void sendWith(const SerializeTag&, int to, int tag, const T1&, const T2&)

template<class SerializeTag, class T1, class T2, class T3>
inline void sendWith(const SerializeTag&, int to, int tag, const T1&, const T2&, const T3&)

template<class SerializeTag, class T1, class T2, class T3, class T4>
inline void sendWith(const SerializeTag&, int to, int tag, const T1&, const T2&, const T3&, const T4&)

Send a message from this context to the given context with the given matching tag and zero, one, two, three or four arguments. The arguments are packed up using the serializer specialized using the given SerializerTag.

Request

template<class Ret>
inline void request(int fromContext, int matchingTag, Ret (*handler)())

template<class Ret, class T1>
inline void request(int from, int tag, Ret (*handler)(T1))

template<class Ret, class T1, class T2>
inline void request(int from, int tag, Ret (*handler)(T1,T2))

template<class Ret, class T1, class T2, class T3>
inline void request(int from, int tag, Ret (*handler)(T1,T2,T3))

template<class Ret, class T1, class T2, class T3, class T4>
inline void request(int from, int tag, Ret (*handler)(T1,T2,T3,T4))

Post requests for messages from the specified context with the specified tag. When a message arrives from that context with that tag, call the provided handler function. The types of the arguments must be compatible with the types sent. The types are deduced on the requesting side from the type of the handler, and at present there is no checking to make sure they correspond to the types on the sending side.

template<class Ret, class T1, class T>
inline void request(int from, int tag, Ret (*handler)(T1), T* obj)

template<class Ret, class T1, class T2, class T>
inline void request(int from, int tag, Ret (*handler)(T1,T2), T* obj)

template<class Ret, class T1, class T2, class T3, class T>
inline void request(int from, int tag, Ret (*handler)(T1,T2,T3), T* obj)

template<class Ret, class T1, class T2, class T3, class T4, class T>
inline void request(int from, int tag, Ret (*handler)(T1,T2,T3,T4), T* obj)

Post requests that include some local data. The local data is passed as the first argument to the handler function, so you can send zero, one, two or three objects to these handlers from the remote context.

RequestWith

These calls are exactly the same as 'request' above, except that they take as their first argument a SerializeTag used to pick specialization of serializes. The serializer on the receiving end should correspond to the serializer on the sending end, though this is not explicitly checked.

template<class SerializeTag, class Ret>
inline void requestWith(SerializeTag&, int fromContext, int matchingTag, Ret (*handler)())

template<class Ret, class T1>
inline void requestWith(SerializeTag&, int from, int tag, Ret (*handler)(T1))

template<class Ret, class T1, class T2>
inline void requestWith(SerializeTag&, int from, int tag, Ret (*handler)(T1,T2))

template<class Ret, class T1, class T2, class T3>
inline void requestWith(SerializeTag&, int from, int tag, Ret (*handler)(T1,T2,T3))

template<class Ret, class T1, class T2, class T3, class T4>
inline void requestWith(SerializeTag&, int from, int tag, Ret (*handler)(T1,T2,T3,T4))

template<class Ret, class T1, class T>
inline void requestWith(SerializeTag&, int from, int tag, Ret (*handler)(T1), T* obj)

template<class Ret, class T1, class T2, class T>
inline void requestWith(SerializeTag&, int from, int tag, Ret (*handler)(T1,T2), T* obj)

template<class Ret, class T1, class T2, class T3, class T>
inline void requestWith(SerializeTag&, int from, int tag, Ret (*handler)(T1,T2,T3), T* obj)

template<class Ret, class T1, class T2, class T3, class T4, class T>
inline void requestWith(SerializeTag&, int from, int tag, Ret (*handler)(T1,T2,T3,T4), T* obj)