|
|
|
eio_packet - Extensible Input/Output Packet File DriverThe EIO_PACKET package provides packet file (annotation, timecode, and data) I/O under the extensible I/O (EIO) system. These functions currently provide a high-level interface to the existing packet file system. In particular, the EIO_PACKET functions make use of a global segment directory (stored in shared memory) and circular disk files.
The global segment directory contains information about the telemetry sessions currently being processed and where their data is located on disk. A circular queue within the directory retains information about the last N sessions processed; once the queue is full, the addition of a new session replaces the oldest session in the queue. Each session entry, in turn, has an associated table of sensor-specific information for that session.
The circular disk files, one for the actual telemetry packet data and one for the annotation/timecode data, are circular queues, stored on disk, of the given types of records. The disk files contain the data from however many of the most recent sessions fit in the files. When the disk queue overflows, the oldest session in the queue is marked invalid and its data on disk is overwritten by data for the new session.
Each record on disk contains data from a single packet source. Record maps in the segment directory map record numbers (i.e., indices into the circular disk files) to the records' source numbers. Records are stored in the disk files on block boundaries. The segment directory table defines the record sizes in bytes, the block sizes, and the number of blocks per record for the different data types (packet, annotation, and timecode).
The EIO_PACKET functions present a record-oriented, logical view of the packet and annotation/timecode data. The application sees a stream of data records, as if the records were being read from or written to a sequential disk file. The EIO_PACKET functions handle all the details of navigating through the various segment directory data structures in order to locate where the data is to be read from or written to in the circular disk files; the EIO_PACKET functions also take care of storing the logical records on block boundaries in the disk files.
When reading data, the application can open a logical data stream for all sources in the current session or in a past session, or for a single source in the session. Random seeking on record boundaries is permitted. End-of-file for a logical stream is signalled when the end of the session is reached.
When writing data, the application should open a logical data stream for the current session (the default if no session is specified). Each output record, from whatever source, is written to the next free slot in the circular disk file and the segment directory is updated to reflect the addition of the new record. Random seeking on an output stream is not currently permitted. As mentioned before, when the circular disk file overflows, the oldest session in the file is marked invalid and its data is overwritten.
The names of the circular disk files are retrieved from the following environment variables:
EPF_ANNOTATION_FILE - is the pathname for the annotation file.
EPF_TIMECODE_FILE - is the pathname for the timecode file;
this is normally the same as the annotation file pathname.
EPF_PACKET_FILE - is the pathname for the packet file.
If the annotation and timecode files are separate files, they will be sparse files; i.e., each file will be sized as if it had records of both types and there will be holes in the file where records of the other type would be.
The following code fragment outputs 5 annotation records for the current session:
#include "eio_util.h" -- Extensible I/O definitions.
#include "apinput.h" -- Annotation/timecode I/O definitions.
...
AnnotationRecord record ;
EioStream stream ;
int source ;
...
-- Open output stream.
eio_open ("/packet/annotation", "-create", -1.0, &stream) ;
record.header.info.type = 1 ; -- Output annotation records.
for (source = 0 ; source < 5 ; source++) {
record.header.source_index = source ;
eio_write (stream, record, sizeof record) ;
}
eio_close (stream) ; -- Close output stream.
The size of the record is assumed to match the record size defined in the segment directory header.
The following code fragment inputs all the timecode records for source number 23 in session number 7:
#include <stdio.h> -- Standard I/O definitions.
#include "eio_util.h" -- Extensible I/O definitions.
#include "apinput.h" -- Annotation/timecode I/O definitions.
...
EioStream stream ;
TimecodeRecord record ;
...
-- Open input stream.
eio_open ("/packet/timecode/session_7/source_23", "-read", -1.0, &stream) ;
for ( ; ; ) { -- Input timecode records until EOF.
if (eio_read (stream, sizeof record, record) <= 0) break ;
printf ("Source #%d ...\n", record.header.source_index) ;
}
eio_close (stream) ; -- Close input stream.
Again, the size of the record is assumed to match the record size defined in the segment directory header.
When the EIO_PACKET package is compiled with the "-DHIPPILIB"
option, the read and write functions access the HIPPI disk using David
Kim's most excellent HIPPI interface library.
When the EIO_PACKET functions are compiled with the
"-DMEDSLIB" option, the segment directory memory is accessed
via the MEDS Library mapRam() facility. Otherwise, the
segment directory memory is accessed using the portable, named shared
memory facility; see shm_util.c in this library. Because the
named shared memory facility uses the named object facility (see
nob_util.c in this library),
applications should close any open streams before exiting.
The segment directory is assumed to have been correctly initialized prior to any packet streams being opened.
There is currently no synchronization between multiple readers and/or writers. The structure of the application system is expected to ensure that no conflicts occur.
The semantics of seeking on an output stream are not clear, so this capability is not yet implemented.
An application can make a single EIO call to read or write multiple records, but, because the records must be individually aligned on block boundaries, there is no performance advantage in doing so.
eio_packet_open() - opens a packet file stream.eio_packet.ceio_packet.h