----------------------------------------------------------------------------- -- -- Onions Network Streams Library -- -- O N I O N S . I N S T R E A M S . F I L E -- -- S p e c -- -- Copyright (C) 1997-1998 Regents of the University of California -- -- Onions is free software; you can redistribute it and/or modify it under -- the terms of the GNU General Public License as published by the Free -- Software Foundation, with or without the single exception listed below; -- either version 2, or (at your option) any later version. Onions is -- distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; -- without even the implied warranty of MERCHANTABILITY or FITNESS FOR A -- PARTICULAR PURPOSE. See the GNU General Public License for more details. -- You should have received a copy of the GNU General Public License -- distributed with Onions; see the file COPYING. If not, write to the -- Free Software Foundation, 59 Temple Place - Suite 330, Boston, MA -- 02111-1307, USA. -- -- As a special exception, if other files instantiate generics from this -- library, or you link this library with other files to produce an -- executable, this library does not by itself cause the resulting -- executable to be covered by the GNU General Public License. This -- exception does not however invalidate any other reasons why the -- executable file might be covered by the GNU General Public License. -- -- Created in 1997 by Roy T. Fielding ----------------------------------------------------------------------------- -- -- The File Input Stream is a stream end that performs buffered reads -- on a filesystem descriptor. Open must be called before reading and -- Close should be called instead of freeing. -- -- I'd be interested to see a performance comparison of this package -- versus Ada.Text_IO input files. -- with Ada.Streams; with Interfaces.C.Strings; with System.Storage_Elements; use System.Storage_Elements; with Onions.Thin; package Onions.Instreams.File is type File_Input_Stream is new Input_Stream with private; type File_Input_Stream_Ptr is access all File_Input_Stream; --------------------------------------------- -- Dispatching Stream Control Operations -- --------------------------------------------- -- Free the storage associated with a stream object. -- procedure Free (SP : in out File_Input_Stream_Ptr); -- Bind an already open descriptor to the stream. -- function Bind (Stream : in File_Input_Stream_Ptr; Filedes : in Thin.Descriptor) return Input_Pipe; -- Open the descriptor associated with a stream. If Name is "", the -- stream is associated with the already open STDIN descriptor, -- otherwise the named file is opened for reading. -- function Open (Stream : in File_Input_Stream_Ptr; Name : in String := "") return Input_Pipe; -- Close the descriptor associated with a stream. Note that this -- is different from a Close of an Input_Pipe in that it does not -- free the stream. I.e., the stream can be Open'd again. -- procedure Close (Stream : in out File_Input_Stream); -- Abort_Stream should only be used if a stream is interrupted -- by the user, or an error occurs that makes the whole stream bad. -- It forces the stream closed without a flush. -- procedure Abort_Stream (Stream : in out File_Input_Stream); -- Reset is like Close, but only resets the file and its buffers -- instead of closing the descriptor. -- procedure Reset (Stream : in out File_Input_Stream); -- Drain the stream by reading once from outbound and processing any -- unprocessed data as if it were the end-of-stream. -- procedure Drain (Stream : in out File_Input_Stream; ItemList : out Bucket_List); -- Name returns a string containing the currently open file name. -- function Name (Stream : in File_Input_Stream) return String; ------------------------------------ -- Ada.Streams Dispatching Read -- ------------------------------------ -- Read obtains stream elements from Stream and places them into -- the components of Item until either each component is filled or -- no elements remain on the stream. Last is set to the index of -- the last component of Item that was filled. This interface is -- defined by Ada.Streams for abstract stream operations. We won't -- use it much because it forces a full data copy when filtering. -- procedure Read (Stream : in out File_Input_Stream; Item : out Ada.Streams.Stream_Element_Array; Last : out Ada.Streams.Stream_Element_Offset); ---------------------------------- -- Data Processing Operations -- ---------------------------------- -- Process does the real work of reading from the file and moves the -- the read data to the Processed read queue. The Unprocessed read -- queue is used as a temporary storage for our free memory list. -- As such, the Everything (end-of-stream indicator) boolean is ignored. -- Raises End_Error when end-of-file is encountered. -- procedure Process (Stream : in out File_Input_Stream; Everything : Boolean); -- Unprocess would be called by Pop if someone foolishly tried -- to pop off the File_Input_Stream. We raise Use_Error instead. -- procedure Unprocess (Stream : in out File_Input_Stream); private type File_Input_Stream is new Input_Stream with record -- Name of the open file -- Filename : C.Strings.chars_ptr := C.Strings.Null_Ptr; -- Fd is the file descriptor when associated with an open file -- Fd : Onions.Thin.Descriptor := Onions.Thin.Failure; -- Allocation of the read buffers can be tricky. If they are too -- small then we perform too many readv() system calls. If they -- are too large then we end up splitting the buckets too many -- times and substantially increasing the data copying. Applications -- that know what they are reading can optimize the mix. -- Bucket_Size : Storage_Count := 1024; Minimum_Buckets_per_Read : Positive := 4; Maximum_Buckets_per_Read : Positive := 8; end record; end Onions.Instreams.File;