Last Updated: 3/15/2005Disclaimer
Introduction
PPC Model
- Pipes, Sockets, and Pseudo Terminals
- Interrupt Driven and Multiplexed I/O
- Remote File Access
- File I/O Interface
- File Access Server
- Communication Paths and PPC Routines
The PPC Library
- The PPC API
- PPC Constants
- PPC Variables
- Compiling and Loading
- Data Structures for PPC
- Example
PCEXEC
- Usage
Related Documentation
Acknowledgements
A special acknowledgement is due to Lee Minner who helped with the socket and remote execution facility in PPC.
Disclaimer
This document was prepared as an account of work sponsored by an agency of the United States Government. Neither the United States Government nor the University of California nor any of their employees, makes any warranty, express or implied, including the warranties of merchantability and fitness for a particular purpose, or assumes any legal liability or responsibility for the accuracy, completeness, or usefulness of any information, apparatus, product, or process disclosed, or represents that its use would not infringe privately owned rights. Reference herein to any specific commercial products, process, or service by trade name, trademark, manufacturer, or otherwise, does not necessarily constitute or imply its endorsement, recommendation, or favoring by the United States Government or the University of California. The views and opinions of authors expressed herein do not necessarily state or reflect those of the United States Government or the University of California, and shall not be used for advertising or product endorsement purposes.Part of this work performed under the auspices of the U.S. Department of Energy by Lawrence Livermore National Laboratory under Contract W-7405-Eng-48.
Introduction
The Portable Process Control library (PPC) is a set of routines to execute and communicate with other processes in environments which permit such operations. The goal is to establish an easy to use interface which can be implemented on a wide variety of platforms. The standard C library I/O interface was taken as a model. In this view, processes are treated as much like files as is possible. In particular, a process is opened and closed as is a file and that means that it is forked by the parent to start with and killed at the end. While a process is open it may be written to and read from with PPC functions which are analogous to the standard C I/O functions fprintf and fgets. In addition, there are functions to monitor the status of the child processes. These do not have precise analogs to file routines, but since the basic interface has been established by the open/close and read/write routines, these have obvious usages.PPC is one part of PACT, Portable Application Code Toolkit. See the section Other PACT Documentation at the end for more information about PACT.
PPC Model
This section describes the interprocess communication (IPC) model used in PPC and gives a high level overview of some of the key features of the library. Much of this discussion is involved with UNIX since that environment is one of the richest (and hence most confusing) environments for IPC. We believe that the concepts are fundamental and hence permit PPC to be ported to environments with different semantics. Also the prevalence of the TCP/IP standard makes it a reasonable one to study in the context of distributed IPC.
Pipes, Sockets, and Pseudo Terminals
In UNIX environments there are three ways for processes to communicate that seem suitable for PPC. They are pipes, sockets, and pseudo terminals (PTYs). Although one might argue that for local processes there is no real advantage to using pipes over sockets or vice versa, PPC supports them both to guard against platforms where one or the other has some non-standard feature. By contrast, PTYs have a crucial significance in that some programs with which a code may wish to communicate behave differently when talking to a terminal than they do when talking to a socket or pipe. FTP is a classic example of this phenomenon. Only sockets are available for remote processes.When an application opens a child process it must specify the IPC medium. In this way the application developer has control over how the parent and child communicate.
Interrupt Driven and Multiplexed I/O
When communicating with one or more child processes, an application is often in the position of having or wanting to get input from the terminal or one or more child processes. There are three ways that are commonly used to do this:
unblocking the input channels and polling in the applicationPPC supports all three of these options.using a multiplex I/O system call (e.g. select or poll)
using interrupts on input channels
Remote File Access
Sometimes applications need to access files on remote systems which cannot be mounted via some standard mechanism such as NFS or AFS. Using the IPC machinery inherent in its design, PPC also supplies a facility to do I/O on remote files. The model here is in two parts.
File I/O Interface
SCORE defines the following set of function pointers:
and macros:
pointer default value io_open_hook fopen io_tell_hook ftell io_read_hook fread io_write_hook fwrite io_setvbuf_hook setvbuf io_close_hook fclose io_seek_hook fseek io_printf_hook fprintf io_puts_hook fputs io_getc_hook fgetc io_ungetc_hook ungetc io_flush_hook fflush io_gets_hook fgets
These give a call compatible interface to the major portion of the standard C file I/O library. It also provides a simple way for an application to supply its own functions to make variations on the functionality. In particular, PPC supplies a set of functions to access files on remote hosts. The function PC_io_connect toggles between the default set of functions and the remote access versions.
#define io_open (*io_open_hook) #define io_setvbuf (*io_setvbuf_hook) #define io_tell (*io_tell_hook) #define io_read (*io_read_hook) #define io_write (*io_write_hook) #define io_close (*io_close_hook) #define io_seek (*io_seek_hook) #define io_printf (*io_printf_hook) #define io_puts (*io_puts_hook) #define io_getc (*io_getc_hook) #define io_ungetc (*io_ungetc_hook) #define io_flush (*io_flush_hook) #define io_gets (*io_gets_hook)
File Access Server
The remote file access functions mentioned in the last section depend on a server running on the remote host. The utililty pcexec is that server.When a request to open a file with a name using the syntax discussed in the section PCEXEC indicates a file on a remote host, pcexec is started on that host in server mode. It then handles all file access requests made by the other calls in the previous section. Any number of files can be managed per host per user. When the last file that the remote pcexec session knows about is closed, pcexec exits. NOTE: if your application crashes, there will most likely be an orphaned pcexec running on the remote host and you will have to kill it yourself.
Communication Paths and PPC Routines
Use PPC routines PC_printf and PC_gets to communicate with child processes. Use C routines fgets and fprintf to communicate with parent processes.Output: The number of items successfully written.
Input: bf a pointer to memory containing the data to be written. type an ASCII string which specifies the data type of items to be written. ni an integer (size_t) number of items to be written. pp a pointer to a PROCESS.
PPC Constants
The following #defined constants should be used in the contexts indicated:
RUNNING 0 return value of PC_status indicating process running STOPPED 1 return value of PC_status indicating process stopped CHANGED 2 return value of PC_status indicating process status changed EXITED 4 return value of PC_status indicating process exited COREDUMPED 8 return value of PC_status indicating process crashed SIGNALED 16 return value of PC_status indicating process signalled PC_LOCAL 102 value indicating process or file on current CPU PC_REMOTE 103 value indicating process or file on remote host USE_PTYS 50 value indicating IPC medium is a pseudo terminal USE_SOCKETS 51 value indicating IPC medium is a socket USE_PIPES 52 value indicating IPC medium is a pipe PC_NDELAY used with PC_set_attr to set non-blocking reads PC_APPEND used with PC_set_attr to specify writes at end PC_SYNC used with PC_set_attr to specify synchronous writes PC_LINE used with PC_set_attr to specify line-at-a-time input
PPC Variables
PPC provides the following global variables:
char PC_err[] Buffer for error messages from PPC routines
int PC_io_interrupts_on Flag which iff TRUE enables I/O interrupts
Compiling and Loading
To compile your C programs you must use the following
#include <ppc.h>in the source files which deal with the library routines.To link your application you must use the following libraries in the order specified.
-lppc -lpdb -lpml -lscore [ -lm ...]Although this is expressed as if for a UNIX linker, the order would be the same for any system with a single pass linker. The items in [] are optional or system dependent.
Each system has different naming conventions for its libraries and the reader is assumed to understand the appropriate naming conventions as well as knowing how to tell the linker to find the installed PACT libraries on each system that they use.
Data Structures for PPC
PROCESS
The data structure which underlies PPC is the PROCESS. It is analogous in purpose to the FILE structure used for file I/O. PROCESS structures contain the information necessary for PPC routines to monitor and communicate with child processes. They are passed to PPC routines the way the FILE structure is passed in the standard C file I/O routines.
Example
The following example is a basic test of PPC in which a small polling loop gets messages from the controlling terminal and passes them to a child process while polling the child process for messages and sending them to the controlling terminal. This program should be entirely transparent to the application.
#include "ppc.h" main(argc, argv, envp) int argc; char **argv, **envp; {PROCESS *pp; char s[BIGLINE]; /* open the process */ if ((pp = PC_open(argv+1, envp, "w")) == NULL) {printf("\nFailed to open: %s\n\n", argv[1]); exit(1);}; printf("\nRunning process: %s\n\n", argv[1]); /* unblock stdin and turn stdout buffering off */ PC_unblock_file(stdin); setbuf(stdout, NULL); while (TRUE) {PC_err[0] = '\0'; while (PC_gets(s, BIGLINE, pp) != NULL) printf("%s", s); /* check the status of the process */ if (PC_status(pp) != RUNNING) {printf("\nProcess %s terminated (%d %d)\n\n", argv[1], pp->status, pp->reason); break;}; /* get any messages from tty, if available */ if (fgets(s, BIGLINE, stdin) != NULL) PC_printf(pp, "%s", s); if (PC_err[0] != '\0') {printf("\nERROR: %s\n\n", PC_err); break;};}; /* close the process */ PC_close(pp); printf("\nProcess test %s ended\n\n", argv[1]); /* turn on blocking for stdin (very important) */ PC_block_file(stdin); exit(0);}PCEXEC
PPC includes an application program called pcexec. It began as a test code for PPC but it has expanded to the point where it has utility in its own right. In fact, pcexec does two jobs. First, it can be used to run other programs in any of the modes discussed in the section The PPC Model. Second, it acts as a file access server for the remote file access capability in PACT.
For questions and comments, please contact the PACT Development Team.