Next: StreamOut
Up: Player Type
Previous: RTLoad

StreamIn

Semantics

A player of type StreamIn corresponds to input that arrives in the form of a stream at a port in a process that has Unix filter semantics. The input in the stream has a syntax, a structure that is imposed on elements in the stream. This structure is specified with the Signature property, whose value represents a single data type imposed on the data in the stream. The signature represents the expectations that the Filter component has for the syntax of the data. When performing Pipe connections during system construction, the signature of a StreamIn player is checked against the signature of the StreamOut player with which it is connected. The Signature property in a StreamOut player defines the actual syntax of the stream.

UniCon StreamIn and StreamOut players allow system designers to view streams of data as entities in a design, and to apply data typing semantics to these entities. System designers can, therefore, describe and reason about properties of streams in ways that are not possible by simply focusing on the source code implementations of the filters.

Component Types In

A player of type StreamIn can legally be defined in components of the following types:

Filter

General

Role Type
Associations

A player of type StreamIn can legally be associated with the following role type in a Pipe connection:

Sink (of Pipe connector)

Properties

The following properties can be legally included in the property list of a StreamIn player:

MaxAssocs

The syntax for the MaxAssocs property in a StreamIn player is a single <integer> surrounded by parentheses:

MAXASSOCS (1)

MinAssocs

The syntax for the MinAssocs property in a StreamIn player is a single <integer> surrounded by parentheses:

MINASSOCS (1)

Signature

The syntax for the Signature property in a StreamIn player is a single <identifier> or "string", surrounded by parentheses:

SIGNATURE (char)
SIGNATURE ("line")

Implementation Considerations

In the source code implementation, a StreamIn player is implemented as a set of system calls to routines that perform input in the form of a stream for a process. For example, in the C programming language, the read system call can be used to acquire input from a particular port (i.e., file descriptor) in the process. Alternatively, formatted I/O functions from the C standard library (wrappers that encapsulate the read and write system calls to make formatting of input and output more convenient for the user) can be used to acquire input from a particular port. In this case, however, the input port must first be wrapped in a data structure of the type expected by the formatted I/O functions; this is done with the fdopen function call.

NOTE: UniCon generates a program that performs the initialization of a pipe and filter system at run-time. This program creates all of the pipes, and hooks each end of each pipe to the appropriate port in one of the filters in the system. Therefore, a filter should never open or close a port; it should assume that the open is done automatically prior to execution of the first line of code in the filter, and that the close is done automatically after the last line of code in the filter is executed. Therefore, when using the read system call to implement the input stream, no calls to open and close are necessary. When any of the formatted I/O routines are used, such as fgets and fgetc, no calls to fopen and fclose are necessary - however in this case one call to fdopen is required to wrap the input port up as a file pointer, the data structure expected by the formatted I/O routines.

The following are examples of StreamIn players in the implementation of a filter:

  #include <stdio.h>

  #define PORT_3         3
  #define PORT_5         5
  #define MAX_BUF_LEN        256
  #define FOR_INPUT        "r"

  /* external data definitions required to support the code fragments below */

  char input_buffer[MAX_BUF_LEN];
  FILE *fp;

  /* the following line of code performs stream input from port 3 
     using the read system call (inside the implementation of a filter) */

  read (PORT_3, input_buffer, MAX_BUF_LEN);

  /* the following lines of code performs stream input from port 5 using 
     the fgets formatted I/O routine (inside the implementation of a filter) */

  fp = fdopen (PORT_5, FOR_INPUT); /* this call happens only once */
  fgets (input_buffer, MAX_BUF_LEN, fp);