11 Implementation

11.1 AMS Messages

AMS messages may be transported within other structures such as MSP messages but the AMS message itself consists of a message type, followed by a structure dependent upon the type. The types are defined in ams_sys.h and the associated structures in ams_struc.h. The message type name has three elements separated by ‘_’:

LOC/REM

Whether local or remote (this or other machine).

type

ACK

Acknowledge

GSOC_START

Start GET/SET/OBEY/CANCEL/CONTROL

GSOC_END

End GET/SET/OBEY/CANCEL/CONTROL

MSG

Message.

DEINIT

De-initialise

INIT

Initialise

CALL

Request remote connection (REM only)

ACCEPT

Accept remote connection (REM only)

IN/OUT

Whether message is in or out

E.g. LOC_ACK_IN, REM_CALL_OUT.

Internal messages are of type LOC_MSG_IN/OUT

The AMS functions will automatically send the right type of message, in the case of ams_send() and ams_reply() this will depend upon their message_function and message_status arguments.

11.2 MSP, Sockets and Queues

MSP uses a single STREAM socket (path) in the INET domain to communicate between any two tasks and a STREAM socket pair in the UNIX domain to send/receive local (internal) messages. Messages on the sockets specify a ‘queue’ in the receiving task for which they are intended and a queue in the sending task to which replies should be sent.

The MSP message reading function accepts a list of ‘receive’ queues on which it should look for messages and the MSP message sending function accepts a ‘send’ queue which specifies a socket and a receive queue in the other task. N.B. the reply queue may be given as MSP__NULL_SENDQ (it is a send queue in the task which has to reply).

AMS uses separate MSP queues within each task for:

• Receiving unexpected messages from other tasks (the command queue).
• Sending unsolicited messages to other tasks (other task’s command queue).
• Receiving replies to a sent message which initiates a transaction – each transaction has its own queue (reply queue).
• Sending replies as part of a transaction (other task’s reply queue)
• Sending local (internal) messages (one for each internal message type).

  sigast_q

  sigext_q

  sigkick_q

  sigresch_q

  sigtimeout_q

• Receiving local (internal) messages (one for each internal message type).

  astint_q

  extint_q

  kick_q

  resched_q

  timeout_q

The AMS user will not need to know about MSP queues.

11.3 Communications Directory

MSP communications are opened between tasks by name. The name lookup is provided by each task making an entry in a directory pointed to by the environment variable ADAM_USER. If ADAM_USER is not defined when a task attempts to register itself with the message system, directory ˜/adam will be used and, if the specified directory does not exist, an attempt will be made to create it.

This results in a file being created in the ADAM_USER directory with a name compounded of the task name and an identifying number (e.g $ADAM_USER/slave_5001). Another task can then open communications by searching ADAM_USER for the right name and using the identifying number.

When a task exits, the AMS exit handler de-registers the task from MSP and the task’s file is removed from ADAM_USER. If the task does not exit normally for some reason, the file in ADAM_USER may get left behind. In this case the file must be deleted explicitly; otherwise the task will refuse to load next time.

11.4 MSP Messages

MSP messages are passed between processes and also added to a queue at the receiving end. Some of the structure components are only relevant when it is being passed, or when it is on a queue.

A received MSP message contains the following information:

• Target queue in this task
• Reply queue in other task
• Actual size of message body
• Message body
• Pointer to next message in the queue

The content of the message body is only understood at higher levels (AMS in this case) – it is immaterial to MSP.