Next: WriteFile
Up: Player Type
Previous: StreamIn

StreamOut

Semantics

A player of type StreamOut corresponds to output in the form of a stream that exits from a port in a process that has Unix filter semantics. The output 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 exact syntax imposed on the stream by the Filter. 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.

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 StreamOut can legally be defined in components of the following types:

Filter

General

Role Type
Associations

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

Source (of Pipe connector)

Properties

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

MaxAssocs

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

MAXASSOCS (1)

MinAssocs

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

MINASSOCS (1)

Signature

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

SIGNATURE (char)
SIGNATURE ("line")

Implementation Considerations

In the source code implementation, a StreamOut player is implemented as a set of system calls to routines that perform output in the form of a stream for a process. For example, in the C programming language, the write system call can be used to write output to 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 write output to a particular port. In this case, however, the output 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 write system call to implement the output stream, no calls to open and close are necessary. When any of the formatted
I/O routines are used, such as fputc and fprintf, no calls to fopen and fclose are necessary - however in this case one call to fdopen is required to wrap the output port up as a file pointer, the data structure expected by the formatted I/O routines.

The following are examples of StreamOut 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_OUTPUT        "w"
  #define ONE_CHARACTER        1

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

  char output_buffer[MAX_BUF_LEN + 1];
  FILE *fp;
  int i;

  /* in each example below the code writes from output_buffer until
     the end of the buffer is reached, or the value `\0' is encountered */

  /* the following lines of code perform stream output to port 3, one character at
     a time, using the write system call (inside the implementation of a filter) */

  for (i = 0; 
       output_buffer[i] != `\0' && i < MAX_BUF_LEN;
       i++)
      write (PORT_3, &output_buffer[i], ONE_CHARACTER);

  /* the following lines of code perform stream output to port 5 using 
     the fprintf formatted I/O routine (inside the implementation of a filter) */

  fp = fdopen (PORT_5, FOR_OUTPUT); /* this call happens only once */
  output_buffer[MAX_BUF_LEN] = `\0';
  fprintf (fp, "%s", output_buffer);