MAILBOXES

A mailbox is a container for holding CSIM messages. A process can send a message (an integer or a pointer) to a mailbox and a process can receive a message from a mailbox. If a process does a receive operation on an empty mailbox, it automatically waits until the next message is sent to that mailbox. As with events, a process can specify a time-out interval when it does a receive.

Declaring and Initializing Mailboxes

To declare a mailbox:
MBOX mb;
Where:

  • mb - is the variable name representing the mailbox (type MBOX)
    Notes:
  • A mailbox must be initialized via the mailbox statement before it can be used in any other statement.

    To initialize a mailbox:
    mb = mailbox("name");
    Where:

  • mb - is the variable name representing the mailbox (type MBOX)
  • name - is the name of the mailbox (quoted string or type char*)
    Notes:
  • A mailbox declared and initialized in the sim (first) process is globally accessible.
  • A mailbox declared and initialized in any other process is local to the declaring process.
  • Local mailboxes can be passed as parameters to other processes.
  • Local mailboxes are deleted when the declaring process terminates.
  • name is used only for output (status, traces).

    To change the name of a mailbox:
    set_name_mailbox(mb,” name”);
    Where:

  • mb - is the mailbox whose name is to be changed (type MBOX)
  • name - is the new name for the mailbox (quoted string or type char*)
    Notes:
  • name is used only for output (status, traces).

    Deleting Mailboxes

    To delete a mailbox:
    delete_mailbox(mb);
    Where:

  • mb - is the mailbox to be deleted (type MAILBOX)
    Notes:
  • If a mailbox is local, only the process that created the mailbox can delete it.

    Using Mailboxes

    To send a message:
    send(mb, msg);
    Where:

  • mb - is the mailbox to which the message is to be sent (type MBOX)
  • msg - is the message, which must be a single integer or a single word pointer (type long)
    Notes:
  • Unreceived messages will be queued in order of arrival (first-in, first out).

    To receive a message:
    receive(mb, &msg);
    Where:

  • mb - is the mailbox from which the message is to be received (type MBOX)
  • &msg - is the pointer to the message (which will be in msg) (type long*)
    Notes:
  • This will receive the next message from the mailbox.
  • If no message is ready, the process will wait until a message arrives at the mailbox. It will restart when a message is received.

    To receive a message, but only if it one arrives within a specified time:
    result = timed_receive(mb, &msg, time);
    Where:

  • mb - is the mailbox from which the message is to be received (type MBOX)
  • result - is a returned indication of whether a message was received (type long):
  • &msg - is the pointer to the message (which will be in msg) (type long*)
  • time - is the maximum amount of time that the process is willing to wait for storage (type double)
    Notes:
  • The process must check the returned value (result) to determine whether a message was received.

    Retrieving Mailbox-Related Information

    These functions each return a statistic which describes some aspect of the usage of the specified mailbox. The type of the returned value for each of these functions is as indicated. The syntax conventions for these statements are as follows:
  • mb - is the mailbox about which information is requested. It must be type MBOX.
  • n - is a returned value of type long.

    Retrieving Mailbox Status Information

    Statement			Returned Value

n = msg_cnt(mb);		returns, for mailbox mb:
    
				number of unreceived messages (if n is positive)
 				number of processes waiting for a message (if n is negative)

    Reporting Mailbox Status

    To print the status of each mailbox in the model:
    status_mailboxes();
    Notes:

  • This report lists each mailbox along with:
  • Number of messages that have not yet been received
  • Number of processes waiting for a message from it
  • The name and id of each process waiting for a message from it
  • The report will be written to the default output location or to that specified by set_output_file