INtime SDK Help
Ports (deprecated)

From INtime 6.0 the INtime Service and Port objects have been deprecated.

New projects should not be started using these features, and existing projects will not work with XM mode. You will receive a compiler warning by default if you use these calls.

Overview

The following table lists common operations on ports and the port system calls that do the operations:

To . . . Use this system call . . .
Service support Add a service to the operating system InstallRtServiceDescriptor
Remove a service from the operating system UninstallRtServiceDescriptor
Allow the caller to receive the address of the interface controlled by the service GetRtServiceAttributes
ntxGetRtServiceAttributes
Allow the caller to specify the address of the interface controlled by the service SetRtServiceAttributes
ntxSetRtServiceAttributes
Port object management Create a message port for access to a given service and return a handle CreateRtPort
CreateRtPortEx
ntxCreateRtPort
Delete a port DeleteRtPort
ntxDeleteRtPort
Bind an address to a port BindRtPort
ntxBindRtPort
Create a connection between a local port and a remote port ConnectRtPort
ntxConnectRtPort
Enable an application to monitor several ports simultaneously via a sink port AttachRtPort
ntxAttachRtPort
End message forwarding between the specified message port and sink port DetachRtPort
ntxDetachRtPort
Return a structure that provides information about the port object indicated by the supplied handle GetRtPortAttributes
ntxGetRtPortAttributes
Make a heap's memory resources available to one or more message ports AttachRtHeap
End the association between a heap and a message port DetachRtHeap
Message transmission Send a data message from a port to a service and return a transaction ID SendRtMessage
ntxSendRtMessage
Send the request phase of a transaction and allocates a storage for the response part of the transaction SendRtMessageRSVP
ntxSendRtMessageRSVP
Send a response message to an earlier received SendRtMessageRSVP message SendRtReply
Cancel synchronous or asynchronous SendRtMessageRSVP messages CancelRtTransaction
ntxCancelRtTransaction
Receive a message at a port ReceiveRtMessage
ntxReceiveRtMessage
Receive a reply message to an earlier SendRtMessageRSVP transmission ReceiveRtReply
ntxReceiveRtReply
Receive a fragment of an SendRtMessageRSVP data message request ReceiveRtFragment
Request memory from the system ntxRequestRtBuffer
Return memory to the system ntxReleaseRtBuffer

This shows the order to make port system calls and lists calls that ports frequently use.

Service support

  1. Make this call add a service to the operating system.
  2. Make these calls to allow the caller to receive or specify the address of the interface controlled by the service.
  3. Make this call to remove the service from the operating system.

Port object management

  1. Make this call to create a message port for access to a given service.
  2. Make this call to create a connection between a local port and a remote port.
  3. Make these calls to enable an application to monitor several ports simultaneously, return a structure that provides information about the port object indicated by the supplied handle, or make a heap's memory resources available to one or more message port objects.
  4. Make these calls to end the association between a heap object and a message port or to end message forwarding from the specified message port.
  5. Make this call to delete a port object.

Message transmission

  1. Make these calls to send a data message from a port to a service, send the request phase of a transaction and allocates a storage for the response part of the transaction, send a response message to an earlier receive SendRtMessageRSVP message.
  2. Make these calls to Receive a message at a port, receive a reply message to an earlier RSVP transmission, or receive a fragment of an RSVP data message request.
  3. Make this call to perform synchronous cancellation of RSVP message transmission.

Heap object management

  1. Make this call to create a heap object.
  2. Make this call to allocate a memory buffer from a heap object and return a pointer to the caller.
  3. Make this call to return a structure that contains information about a heap object.
  4. Make this call to return a previously-allocated buffer to its heap.
  5. Make this call to delete a heap object.

Overview

A port is the object which allows access to the features provided by INtime services. A process that uses a port object can send messages through the port to an INtime service, or can receive messages through the port from the service. Other operations possible on ports include:

Operations on ports fall into two board categories: setup and message-passing.

Creating a port

When you create a port, you use CreateRtPort. These are the resources you specify when you create a port:

Allotting memory resources for message storage

You can attach a heap object to a port to provide a private memory resource. This allows incoming messages to be handled quickly, while controlling the resources used by a service. The RT kernel gives the receiving task a pointer to either the single buffer or to the list descriptor which holds the pointers for all the buffers in the list.

A heap may be attached or detached at any time during the existence of the port. Only one heap may be attached to the port. Use AttachRtHeap and DetachRtHeap.

The heap's particular importance to INtime service is that it provides an efficient way of sharing a memory resource between more than one process, with very low overhead. If a user process allocates its data messages from an heap attached to the port where the messages will be sent, the kernel is very efficient at mapping the data buffers to the service process.

Deleting a port

When you delete a port using DeleteRtPort (or by deleting the process which created it), the kernel deletes all messages queued at the port and cancels all outstanding transactions for the port. The kernel deletes message buffers allocated from the port's heap object (if any) and awakens any task waiting at the port with an E_EXIST condition code. If you delete a sink port (described later) that is attached to one or more ordinary ports, the kernel detaches them.

Identifying a port

The information below describes the ways a port is identified.

Identifier How used
Service link Each port is created for a particular INtime service. Messages sent to a port for a given service can only be interpreted by that service and can only be delivered to a different service by the service it is created for.
Port ID The Port ID identifies the port among all those for a given service on a given instance of the real-time kernel. The port ID is like an address for each port within a service.
Hardware interface address Also known as Host ID. This usually applies to hardware services which manage an interface to a medium such as a bus or network where each attachment is differentiated by its logical address. The format of the hardware address is variable, depending on the medium the service is managing.
Generalized address A generalized address is a structure which combines the Port ID and Hardware Address. It is independent of the operating system in use so it may be used, for example, to identify a port on a network shared by different systems. Use the generalized address rather than the handle to identify the destination or source port of messages.
Handle This is an identifier specific to the INtime kernel. The handle is used as an object reference in the local system and, for example, for cataloging the port in an object directory, to attach a port to a sink port, and to delete a port.

Passing messages

Messages are the means to convey data and instructions to and from an INtime service. There are certain features common to messages in all services, which are described here.

Message storage

Although the control and data portions are combined when sent in a message, they are stored differently at the receiving port.

Sending simple messages

These messages follow the data mailbox model. You can use SendRtMessage to send the message to a port. Use ReceiveRtMessage to receive a message from a port. Sending a message to a port invokes an internal handler in the service which is responsible for handling the message. The precise action performed depends on the design of the service.

By calling ReceiveRtMessage a user process receives the next available message on the port. If no message is currently available the calling thread is put to sleep for the time limit specified in the call, or until a message is delivered to the port by the service.

Message format and processing

A message consists of a required control (or header) part and an optional data part. In general a service will use the control part to decide what to do with the data part, but has in general no need to know the contents of the data part. The maximum size of the control part is determined by the service, and is determined when the service is installed.

Data messages may be any size, including zero, and may be contiguous, or made up of a list of buffers. A message with no data part is known as a control message.

Sending request/response messages

A transaction provides a client-server communication model. Clients send request messages to servers and servers send responses back. A server may be the service itself, or an application on a port to which messages may be delivered by this service. This model includes the ability to:

Transaction (message pairs)

The kernel uses a transaction ID to match responses to requests. The request is delivered to a port using SendRtMessageRSVP, whereupon the service will transmit the message from its interface. On successful transmission, or if transmission was asynchronous, a transaction ID is returned to the caller. The caller uses this transaction ID to make a call to ReceiveRtReply and is put to sleep awaiting a response.

When the service receives a response from the interface, it delivers it to the task waiting in ReceiveRtReply and wakes it up. The service uses the RSVP buffer supplied in the original SendRtMessageRSVP call to deliver the data and a pointer to this buffer is returned to the caller of ReceiveRtReply.

The client supplies a pointer to a response buffer if it expects a data message in response. This buffer is allocated from the client task's job; it is not allocated from the port's heap.

Request-response transactions

Messages may also be part of a transaction, which consists of a request message and a response message. A transaction is identified by a transaction ID which is associated with the messages in a transaction. Simple messages have no transaction ID. When a request message is sent to a service, a corresponding response message should be expected. Similarly, if an application receives a request message from a service, a response message should be returned to the service in reply.

Transaction pairs provide a client-server communication model. Clients send request messages to servers and servers send responses back. A server may be the service itself, or an application on a port to which messages may be delivered by this service.

Basic request-response transactions

The client sends a control/data message that tells the service to perform a process on the data (for example, write it to a disk):

The client task calls SendRtMessageRSVP. The client calls ReceiveRtReply and goes to sleep waiting for the response.

The service delivers the data to the interface and waits for a response (for example, the disk drive returning its status). It then packages the response control and data message and delivers it to the task waiting for the transaction to complete, using the transaction ID supplied by the client when it calls ReceiveRtReply.

Unsolicited message from service to client

To be developed.

Forwarding messages from sink ports

This describes the method by which a single thread can receive messages at more than one port, and how a port can be configured to deliver to a single remote address.

Message forwarding allows messages from several connected ports to be received by a single task waiting at a sink port. Sink ports help avoid duplication of code in several tasks. All messages come to the sink port, which forwards them to the appropriate task. The sink port must be on the same host as the receiving task.

The example below shows an intermediate service which is required to process messages from two hardware services. Instead of creating a service task for each port, a sink port is used to receive messages from each of the hardware service ports:


About heap object management functions

The interfaces described in this section provide the object management interface for the heap object. A heap is created, then buffers may be requested from the heap and subsequently released to the heap. Finally, the heap may be deleted. Two additional interfaces are provided; one to find the size of a buffer allocated from a heap given the heap token and the buffer pointer, and one to interrogate the heap object to determine how much of its resources have been used.

If an application creates a heap, that heap's segment is mapped into the process' virtual segment. No virtual reference is returned to the user, because no direct access of the segment is intended. When buffers are allocated from the segment, the interface library adjusts the buffer offset according to the caller's mapping of the heap segment so that a valid pointer is returned to the caller.

If a heap token is used by a process which did not create it, the heap object must be mapped into the new job's virtual segment and an internal reference of this mapping be kept by the object. This has two purposes:

See Also

INtime services