Go to the first, previous, next, last section, table of contents.

Runtime Facility (in C)

There is a set of "glue" functions written in C to allow existing applications to talk with AgenTalk-based agents. Currently this C-based runtime facility is limited to the basic message handling functionalities, namely,

message class definition (without inheritance)
registration of message handler for each message class (no pattern match is supported.)

AgenTalk.h file is the include file for C-based runtime facility. An application program should include this file to utilize this runtime facility.

Supported Data Type in C

Several data types are defined. () denotes the current implementation.

AtName: symbol (in a Lisp sense) (const char)
AtBoolean: boolean values: TRUE or FALSE (int)
AtError: error code (int)
AtInteger: integer in a message slot (long)
AtFloat: floating number in a message slot (double)
AtString: string in a message slot (char *)
AtDataType: specifies the data type of message slot (enum = { kAtInteger, kAtFloat, kAtString})
AtAgent: agent (struct AtAgent)
AtAgentId: agent ID (const char)
AtMsg: message (struct AtMsg)
AtMsgId: message ID (const char)

Agent in C

An agent is implemented as a data structure of the AtAgent or a data structure which has the same members in its top as the AtAgent. The following is the typical steps of the agent definition.

define a structure of an agent
allocate a memory for the agent
call AtSetAgentName to assign a name to the agent
call AtRegisterAgent to register the agent

Function: void AtSetAgentName (AtAgent *agent, AtName *name)

The name of agent is set to name.

Function: void AtRegisterAgent (AtAgent *agent)

This function registers an agent at the post-office.

Note: Current implementation does not support the functionality corresponding to the function wait-for-message in the Lisp version. Thus, AtRegisterAgent returns without waiting for the confirmation message from the post-office. An interim solution is to check if the _agentId member of an agent is not NULL. If this value is not NULL, the registration of the agent has succeeded.

Message in C

Function: void AtDefineMsgClass (AtName *class, ...)

This function defines a message class class. Following class, a slot name (AtName *) and its data type (AtDataType) can appear. Multiple slots can be defined. NULL terminates the slot definition.

The following three data types as a slot value are supported.

kAtInterger
kAtFloat
kAtString

No inheritance mechanism is implemented in the message class.

Example:

AtDefineMsgClass("ANNOUNCEMENT", 
                 "SPECIFICATION", kAtString,
                 "EXPIRATION", kAtInteger, NULL);

Function: AtMsg * AtCreateMsg (AtName *class, AtName *receiver, AtName *sender, ...)

This function creates a message (structure) of the message class class. receiver specifies the name of a receiver agent, and sender specifies the name of a sender agent. Following these arguments, pairs of the slot name and its value can be specified. The argument list should be terminated with NULL.

Example:

AtMsg *msg = AtCreateMsg("ANNOUNCEMENT", "*", "ME",
                         "SPECIFICATION", "TASK1", 
                         "EXPIRATION", 3003044053, NULL);

Function: AtMsgId * AtSendMsg (AtMsg *msg)

This function sends msg, and returns its message ID. If the transmission fails, NULL is returned.

Function: AtName * AtGetMsgSender (AtMsg *msg)

This function returns the name of a sender agent of the message msg.

Function: AtError AtGetMsgSlotValue (AtMsg *msg, AtName *slot, void *value)

This function sets the memory area pointed by value to the value of slot slot of a message msg. The data type of the slot is obtained from the definition of the message class of msg. The memory area pointed by value should be able to hold the object of this data type.

Note: When the data type of the slot is kAtString, the value is not copied; simply the pointer to the string is set to value. Thus, the application program should not physically modify the returned value.

Function: int AtSprintMsg (char *s, AtMsg *msg)

This function prints out the content of msg to the string s. The format of this print out is the same as the format used in the communication between the mailbox and the post-office. This function returns the length of the resultant string.

Function: void AtFreeMsg (AtMsg *msg)

This function frees the memory area occupied by msg. The memory area used to hold the message ID is also freed. However, the value of slots, the sender, and the receiver are not freed.

Message Handler in C

Currently, C runtime facility does not support pattern matching. Instead, a message handler can be associated with each message class.

Data Type: AtMsgHandler

AtMsgHandler is the data type of a message handler. It is defined as follows.

typedef void AtMsgHandler (AtMsg *msg, AtAgent *agent)

Note: In the message handler, you need not call AtFreeMsg to free the memory occupied by msg. The deallocation of msg is done inside the caller of the message handler.

When the data type of a slot is kAtString, the memory area holding this string is freed after the message handler returns. Thus, if an application program wants to keep this string value, its copy should be made inside the message handler.

Function: AtError AtInstallMsgHandler (AtName *class, AtMsgHandler *handler)

This function associates handler with the message class class.

Function: AtError AtHandleInput (int fd)

This function is provided to be used with XtAppAddInput in the Xt toolkit for handling the input from the socket designated by fd.

When the EOF is detected, the connection to the post-office is closed, and kAtConnectionClosedError is returned. If this function is registered with XtAppAddInput, this input should be removed by calling XtRemoveInput.

Miscellaneous Functions in C

Function: void AtInitialize (AtName *locationName)

This function initializes the runtime facility. This should be called once at the program initialization. The location name needs to be given by locationName.

Function: int AtConnect (char *host, char *service, int port)

This function establishes the TCP connection to the post-office. host is the name (or its IP address) of the host of the post-office process, service is the name of this post-office service, and port is the port number for this connection. Either service or port should be specified.

When a connection is established, this function returns the file description of the socket of the connection (The socket interface is used). Otherwise -1 is returned.

Function: AtBoolean AtMailboxReadyp (void)

When the mailbox associated with the runtime facility has been initialized, TRUE is returned. Otherwise FALSE is returned.

Note: Actually, when a assign-name message is arrived from the post-office, the initialization of the mailbox is completed.

Macro: AtSetDebugEntry (type, (void (*)(AtMsg *))func)

There are hooks for invoking a function when a message is correctly received and a message is sent. AtSetDebugEntry is a macro and type can take either received or sent. func is the function to be called.

Go to the first, previous, next, last section, table of contents.