# Section 8.1.1.12:
$PORT

###### abstract class $PORT{T < $IMMUTABLE} < $INOUT_DEVICE

#### Formal Definitions

This abstract class defines a state component which is a set of all instantiations of objects of any class sub-typing from this class in addition to the vdm model types used wherever this class name is used. Note that SAME has to be an instantiated class, not an abstract one.

The type definitions in this abstract class specification fall into two groups :-

1. The definition of $PORT{T} itself (including SAME).
2. The auxiliary vdm type needed to define a Sather type argument used in the feature definitions which follow.

types
SAME = object_type ;
$PORT_T = set of object_type
-- Auxiliary Types
Immutable_Type = @T
state
references : $PORT_T
inv ref_types ==
forall obj in set ref_types & sub_type($PORT_T,obj)

NOTE | See the important note about vdm state in the notes on vdm-sl usage in this specification.

This abstract class defines the abstract concept of a port through which a program may import or export values. The operation of the port may be either synchronous or asynchronous. A value exported through a port may or may not be the value returned by the next call to the import procedure (if the port is also readable), dependent upon the real device port to which an instantiation of this abstraction is connected!

NOTE | The class parameter is intended to be an object class which corresponds in size (see AVAL::asize) to the width of the actual port (indicated by the create or open feature argument) involved. The meaning of any class sub-typing from this one for which this is not true is undefined!

#### create

This feature creates a port for an object (which is normally expected to be immutable). The port created is attached to the handle argument, the value of which is execution environment defined.

create | (
| ident : $REFERENCE
| ) : SAME

##### Formal Signature

Since this is a creation routine there is no self argument.

create(ident : $REFERENCE) res : [SAME]

##### Pre-condition

Since the language system can know nothing about the execution time environment, no meaningful pre-condition can be set. It is therefore vacuously true.

##### Post-condition

post (res = nil)
or writable(res)

This routine creates a new port object for output of the width specified by the size of the argument type. The resultant object is connected in an implementation-defined way to the port identified by the implementation-specified identity used as parameter. The port created may be used for both input and output if the actual device connected to it permits this. It is implementation-defined if more than one such port object can be attached to the port identified. If this creation is unsuccessful then void is returned.

#### open

This feature provides a facility to connect the program to an external port for reading only. It is a creation routine with another name.

open | (
| ident : $REFERENCE
| ) : SAME

##### Formal Signature

open(ident : $REFERENCE) res : [SAME]

##### Pre-condition

Since the state of a port, whatever its handle, is determined by the execution environment from time to time, the pre-condition must be vacuously true.

##### Post-condition

post (res = nil)
or readable(res)

This routine creates a new port object for reading only of the width of the argument class which is attached in an implementation-defined way to the port identified by the implementation-specified 'name' parameter. It is implementation-defined if more than one such object can be attached to the port identified. If this creation is unsuccessful then void is returned.

#### get

This is the sole input feature for a port. The value obtained may or may not be different from any previous use. This is dependent upon the actual device in use. Execution may only be suspended if there is no immediately available value (if, for example, some I/O protocol has not yet been completed).

get | : T

##### Formal Signature

get(self : SAME) : Immutable_Type

##### Pre-condition

pre readable(self)

##### Post-condition

This is vacuously true since any external fault causes the exception condition.

##### Exception condition

The semantics of raising an exception for the port is that of the raise statement which is defined in section 6.7 of this specification.

errs External_Fault : (res = nil) -> raise self

This feature returns the next value available at the device port unless an exceptional condition occurred, when an exception is raised. It is implementation-defined whether each use of this feature provides a new value or merely the currently available value (if any).

#### put

This is the only output feature required of a sub-typing class. Note that the formal definition does not require buffering. If there should be some protocol error than an exception is raised.

put | (
| val : T
| )

##### Formal Signature

put(self : SAME, val : Immutable_Type)

##### Pre-condition

pre writable(self)

##### Post-condition

This is vacuously true since any external fault causes the exception condition.

##### Exception condition

The semantics of raising an exception for the port is that of the raise statement which is defined in section 6.7 of this specification.

errs External_Fault : (res = nil) -> raise self

This routine makes available a facility to send the given value out to the device connected to this port. When this procedure returns, the implementation must guarrantee that the value provided has/will be sent through the port before the value argument to any subsequent call of this routine for this port. If there is an external device error then an exception is raised.

#### synchronise

This feature is provided to drain any buffered output to the external device.

synchronise |

##### Formal Signature

synchronise(self : SAME)

##### Pre-condition

pre writable(self)

##### Post-condition

The specification presumes that any error will have raised an exception when previous put operations took place. The post-condition is therefore vacuously true.

This feature ensures that the most recent value put to the device (if any) has been emitted through the port. If the port is controlled by a device which operates a hand-shaking protocol then the device has acknowledged receipt of the value.

#### close

This final feature disconnects the program from the external device accessed through the port. Any data buffered for output is discarded.

close |

##### Formal Signature

close(self : SAME)

##### Pre-condition

There is no necessary pre-condition, since if a previous attempt at closing the connection had taken place then no action need be taken, if not then the action taken will result in the disconnection anyway!

pre true

##### Post-condition

post not (writable(self)
or readable(self)

This feature takes implementation-dependent actions in order to dissociate the program from the port resulting in the ability neither to put nor to get.

| Language Index |  | Library Index |  | Basic Index

Comments or enquiries should be made to Keith Hopper. Page last modified: Wednesday, 22 November 2000. |