Previous: Mailbox | Next: Parameterized Mailbox

Built-in methods in Mailbox (contd.)

get()

The method get() retrieves a message, if available, from a mailbox. If a message is not available, a call to get() blocks. Also, since a message can be any singular type, if the actual type of the message retrieved does not match with the code that calls get(), there will be a run-time error. The following is the prototype declaration for get()

task get (ref singular message);

An example of retrieving messages that we put in our mailbox uGotMail earlier is shown below. Note that, a mailbox is a FIFO - the first message that's put in will be popped first.

   int int_msg; 
   string str_msg;
   ...
   if (we_need_msgs) begin
      uGotMail.get(int_msg); // int_msg := msg1
      uGotMail.get(str_msg); // str_msg := msg2
   end 

An obvious question to ask at this point will be what will happen if we, by mistake, assigns a retrieved message to a wrong type? For example, what will happen if we had the previous example as follows.

   /* WRONG EXAMPLE */
   if (we_need_msgs) begin
      uGotMail.get(str_msg); // str_msg := an int message
      uGotMail.get(int_msg); // int_msg := a string message
   end 

The answer is: it will create a run time error with unpredictable consequence.

try_get()

The method try_get() is similar to get(), except that itis non-blocking. So, if a message is available, it will retrieve the message (and will return 1). If a message is not available, it will return 0 and, if a message of wrong type is available (indicating a possible programming error), it will return -1. The prototype for try_get() is shown below.

function int try_get (ref singular message);

The following example shows how try_get() is used for checking a mailbox for message repeatatively with a delay of DELAY.

   int flag;

   always begin  
      #DELAY;
      flag = uGotMail.try_get(s);
      if (flag == 1)
         // process the message   
      else if (flag == 0) 
         ; // wait - do nothing
      else if (flag == -1) 
         // do error processing
   end    

peek()

Many times, it is useful to look into a message but without yanking it from the mailbox. The peek() method provides such a facility. It lets you copy a message from the mailbox, without actually deleting it from the mailbox. If there is no message in the mailbox, the behavior of peek() is identical to get() - it blocks until a message is available in the mailbox.

The prototype for peek() is shown below.

task peek (ref singular message);

try_peek()

The try_peek() method is to peek(), what try_get() is to get() - it copies a message from a mailbox, if one is available. However, if a message is not available, it does not block. The try_peek() method returns 1, if a message is available, 0, if not and -1, if a message of proper type is not available. The prototype for try_peek() is shown below.

function int try_peek(ref singular message);

Previous: Mailbox | Next: Parameterized Mailbox