Skip to content

msu receive function

Jump to bottom
Isaac Pedisich edited this page Oct 5, 2017 · 4 revisions

MSU Receive function

Each MSU must define a recieve() function which is to be called when a message is dequeued into that MSU.

The signature of this receive function must be:

recieve(struct local_msu *self, struct msu_msg *msg)

The MSU may perform any action is likes with the received message. Three actions exist which warrant particular explanation.

  1. Retrieving of state
  2. Sending to the next MSU
  3. Freeing MSU messages

State retrieval

MSU state comes 3 forms.

Type-scope state

Type-scope state can be initialized in the init_type msu_type function, which will be called only once, on initialization of the runtime. This state should simply be stored in a static variable within the msu's source code.

MSU-instance state

MSU-instance is accessible through self->msu_state, and is particular to an instance of an MSU. This state can be instantiated in the init() msu_type function.

MSU-message state

MSU-message state is state which is specific to an msu message key, and should be stored over the lifetime of a request. This state can be interacted with through three functions (declared in src/runtime/msu_state.h)

void *msu_init_state(struct local_msu *msu, struct msu_msg_key *key, size_t size);
void *msu_get_state(struct local_msu *msu, struct msu_msg_key *key, size_t *size);
int msu_free_state(struct local_msu *msu, struct msu_msg_key *key);

The key variable in each function refers to the message's header, accessed via msg->hdr.key. These states are unique to an MSU's instance and the provided key, and should be freed when it is certain that the MSU will not be called again with the same key.

See [MSU message keys](MSU message keys) for more information on setting/generating keys.

Message passing

When an MSU has completed its execution, it may optionally want to call another MSU. That can be done through the interfaces defined in src/runtime/msu_calls.h (doxygen available here).

These functions come in two varieties:

  1. call_* functions, which accept a message header. These are meant to be called to continue a chain of MSU calls associated with a single message. This maintains the message's header, and adds to the list of MSUs that have accessed that specific message.

  2. init_call_* functions, which accept a message key. These functions are meant to be used when a message first enters the system, to do the initial call of an MSU. To call these, first generate the key that is to be associated with the message. Note that the key is copied once in the function, so a locally-scoped key is fine.

See [MSU message keys](MSU message keys) for information on how to create a message key.

Freeing MSU messages

Note when creating an MSU that any data created within that MSU is not automatically freed. This means that if a message is created in one MSU, then passed to a second, the second MSU must explicitly free the message's data when appropriate.

That said, destruction of the msu_msg (including msg.hdr) is handled automatically, and MSUs should never free the msu message itself.

Clone this wiki locally