OVM Interthread Messaging Introduction

OVM provides special commands, and functions (of the form MSG) which are intended for passing messages between an OVM script, and other threads in a multithreaded application. To make use of these interthread messaging keywords your application must explicitly support them. This section will describe the expected generic behaviour of the interthread messaging keywords.

If your application does support OVM interthread messaging you should refer to your application’s documentation in preference to this document.

Receiving OVM Interthread Messages

OVM supports only a single send / receive queue per OVM instance. For this reason the msg keywords do not require a queue handle.

You can check if any interthread messages are waiting to be read using the msgidle function. If msgidle returns true it means there are no messages waiting to be read.

@if msgidle() then comment("No messages")

The msgwait function waits for up to a specified timeout period (in milliseconds) for an interthread message to become available.

@if msgwait(1000) then else comment("No messages")

The msgnext function attempts to get the oldest (first) message from the message queue. If a message was available msgnext returns true otherwise msgnext returns false. The msgnext function takes an optional integer variable name as a parameter. If a message was successfully got then this variable will hold the message type.

@integer messtype
@if msgwait(1000) then call msgnext(messtype)

The msgnextoftype function attempts to get the oldest (first) message from the queue that is of the specified type. This allows you to check for more important messages before processing other messages. On success msgnextoftype returns true.

@constant IMPORTANTMESSAGE = 100
@if msgnextoftype(IMPORTANTMESSAGE) then

Every time you receive a message with msgnext, and msgnextoftype you can no longer access a previously received message.

Retrieving Data from the Attributes of the Last Received Message

Once you have successfully received an interthread message you generally will need to retrieve data from it.

To determine the type of the last received message use the msggettype function.

successfully received a message

@if msggettype() = 1 then
@else if msggettype() = 2 then

Messages will usually also have 1 or more "attributes" depending on their type. Each attribute will usually contain data the OVM script will need to process. Attributes (when supported) are numbered starting at 1.

To find out the amount of data a given attribute is holding use the msggetattrsize function which returns the size in characters / bytes of data held by that attribute.

@integer numbytes = msggetattrsize(1)

The above example gets the size in bytes of data held in the first attribute.

When the amount of data held is small enough to be held in a string variable you can use the msggetattr function to retrieve the data into the string variable. On success msggetattr returns true.

@string buffer
@if msggetattr(1,buffer) then

You can use the msgchangeattr function to alter the value of attributes of the last received message. This can be useful when a message requires minor alteration before being forwarded or processed further. (e.g. input entry validation)

@string newAttrib1 = "new value"
@call msgchangeattr(1,newAttrib1)

When the amount of data is too large to be held in a string you can have the data saved to a file using the msgsaveattr function.

@if msggetattrsize(1) > 255 then call msgsaveattr(1,"attr1.dat")

The number of bytes saved is returned by msgsaveattr.

Creating, and Sending OVM Interthread Messages

To create a new interthread message use the msgcreate command. Note that creating a message is not the same as sending it.

@msgcreate(10) ! create a message of type 10

Creating a new message destroys any unsent message.

To forward the data from the last received message to a new outgoing message use the msgforward command. Whether the type of the new message must be the same as that of the message being forwarded depends upon the application. It is also application dependent if the last received message is still available after a forward.

@if msgnext() then
@if msgtype() = 10 then msgforward(10)

Note that forwarding a message does not actually send the message. It just makes it the next message to be sent. Also, as with msgcreate, msgforward destroys any unsent message.

To actually send the last created message use the msgsend function.

@if msgsend(1) ! send last created message to destination 1

The parameter of msgsend identifies where the message should be sent. This would typically be the incoming message queue of another thread of the application. Whether or not the last created message still exists after sending is application dependent.

Setting the Attributes in the Last Created Message

To set the data in an attribute of the last created / forwarded message you can use msgsetattr, and msgloadattr.

The msgsetattr command sets the attribute data from the results of an expression.

@msgcreate(3) ! create a type 3 message
@msgsetattr(1,"Shutting down") ! set the first attribute’s data
@msgsend(1) ! send to destination 1

The msgloadattr function loads the specified attribute with data from a specified file returning the number of bytes stored in the attribute.

@integer numbytes = msgloadattr(1,"mydata.dat")

Miscellaneous OVM Interthread Message Issues

All msg keywords rely on the application to support them. It is up to the application developer to ensure that the implementation of interthread messages is actually thread safe, efficient, and free of bugs.

Although the msg keywords were intially designed for interthread communication there is no reason for an application not to use them for other purposes that fit a message processing model such as sending, and receiving email, or communicating between @run’d, and @include’d scripts.

In the future some of the keywords that are currently functions may become commands or vica-versa. Also, some keywords may be made more flexible in the parameters they can take.

It is up to the application developer to provide documentation of the exact behaviour of the keywords they choose to implement for their application.

At present there are no plans to allow OVM to support more than a single input / output queue, or to allow more than 1 message to be received or created at a time.

For many applications implementing both streams, and interthread messages that interact makes sense. Particularly interthread messages can be used to efficiently notify an OVM script of stream events (eg data available, disconnection, break received).

This publication has been prepared and written by Telstra Corporation Limited (ACN 051 775 556), and is copyright. Other than for the purposes of and subject to the conditions prescribed under the Copyright Act, no part of it may in any form or by any means (electronic, mechanical, microcopying, photocopying, recording or otherwise) be reproduced, stored in a retrieval system or transmitted without prior written permission from the document controller. Product or company names are trademarks or registered trademarks of their respective holders.

Note for non-Telstra readers: The contents of this publication are subject to change without notice. All efforts have been made to ensure the accuracy of this publication. Notwithstanding, Telstra Corporation Limited does not assume responsibility for any errors nor for any consequences arising from any errors in this publication.