A handler is a function used to receive messages from the network. The
user's code does not directly call handler functions. Rather, as a
message is extracted from the network, FM_extract() passes
control to the handler that FM_begin_message() had previously
associated with that message. Handlers take two arguments: an
FM_stream *, which represents the incoming message stream, and an
unsigned int, which is the sender's node number. Handlers return
either FM_CONTINUE to allow FM_extract() to continue
extracting or FM_QUIT to stop FM_extract()
prematurely.(18)
The sender does not specify the handler by address, but rather by a
handler ID returned to the receiver by FM_register_handler().
Note that using IDs instead of function addresses enables the sending
and receiving processes to be represented by different binaries (e.g.
in a client-server application).
Handlers in FM are different from the handlers used in all other handler-based messaging layers. The key distinction is that FM 2.1 handlers begin executing as soon as the first---as opposed to the last---piece of the message arrives. Furthermore, the target location of each piece of data can be specified dynamically, even after reading a previous piece of data from the same message stream. This makes message reception far more flexible than what is possible with a more traditional scatter vector.
FM 2.1 imposes a few limitations on how handlers must be written:
FM_stream * passed into a handler is valid only within that
handler and only until the handler returns. A handler may not use an
FM_stream * not passed directly to it by FM_extract() to
receive data from the network. (Of course, a handler can use an
FM_stream * not passed to it by FM_extract() to
send data.)
FM_stream * to another function.
struct. For example, both initializers and
static declarations are invalid within a handler.
Go to the first, previous, next, last section, table of contents.