NAME

mr_init – initializes ports for a thread

SYNOPSIS

#include <mrendez.h>

int mr_init( int nports );

DESCRIPTION

The mr_init() primitive is used to create and initialize ports for a thread that can be used for receiving messages with the mr_receive() call. nports defines the number of ports to create. A thread can have a maximum of 32 ports.

The most common mistake made using mr_init() is to fail to initialize the thread using the call before another thread does an mr_send(). This leads to a failure of the send call and users often don’t understand the system behavior.

The best practice is to immediately ensure that a thread, which uses rendezvous style messaging and does a mr_receive(), runs immediately after creation and that initialization is the first thing that this thread does. Higher priority threads become ready to run and run immediately. sched_yield() is generally an easy means to allow threads at the same priority to run immediately. For threads at lower priorities, the priority can be temporarily increased and decreased using pthread_setprio(). Priority increase is done in the creating thread; however, it is best to put the priority reduction in the low priority thread after the call to mr_init().

The reason that ports are not created automatically is because they require extra space per thread. Future versions will provide an automatic means to do this for all threads with backward compatibility.

RETURN VALUES

If successful, mr_init() returns 0, otherwise it returns -1 and sets errno to indicate the error condition.

ERRORS

EINVAL

The nports specifies a value of 0 or greater than 31.

EEXIST

The nports have already been created.

ENOMEM

Not enough memory.

SEE ALSO

mr_receive()