⟦9d5fb3f95⟧

TextFile

WITH Byte_Defs;
WITH Transport;
WITH Transport_Defs;

PACKAGE Transport_Stream IS

   -- A transport stream combines a transport.connection with
   -- some buffering, and provides a simplified transmit/receive
   -- interface.

   -- A facility is provided for creating pools of streams.
   -- Allocating and deallocating streams is usually fast.
   -- Unused streams are scavenged periodically.

   -- This package is useful for programs which want to communicate
   -- with some other machine, but don't want to be bothered with
   -- setting up and tearing down transport.connections, or don't
   -- want to deal with transport status codes.


   TYPE Stream_Id IS PRIVATE;


   PROCEDURE Allocate (Stream     : OUT Stream_Id;
                       Connection :     Transport.Connection_Id);

   -- Create a stream around the given connection.  Such a
   -- stream has no pool, and will be closed as soon as it
   -- is deallocated.  The caller is responsible for opening
   -- and connecting the given connection.


   PROCEDURE Allocate (Stream  : OUT Stream_Id;
                       Is_New  : OUT Boolean;
                       Network :     Transport_Defs.Network_Name;
                       Host    :     Transport_Defs.Host_Id;
                       Socket  :     Transport_Defs.Socket_Id);

   -- Find or create a stream to the given network/host/socket.
   -- Is_New is returned true iff a new connection had to be
   -- built: i.e. there was not already a stream in the pool.


   PROCEDURE Deallocate (Stream : Stream_Id);

   -- Return a stream to its pool.  It will not be
   -- disconnected immediately, but may be scavenged.


   PROCEDURE Disconnect (Stream : Stream_Id);

   -- Disconnect the transport connection.


   PROCEDURE Transmit (Into : Stream_Id; Data : Byte_Defs.Byte_String);
   PROCEDURE Receive  (From : Stream_Id; Data : OUT Byte_Defs.Byte_String);

   PROCEDURE Flush_Transmit_Buffer (Stream : Stream_Id);
   FUNCTION  Flush_Receive_Buffer
               (Stream : Stream_Id) RETURN Byte_Defs.Byte_String;

   -- If anything goes wrong with the above operations, the
   -- stream is disconnected, any associated buffers are
   -- deallocated, and the following exception is raised:

   Not_Connected : EXCEPTION;

   -- Each stream is unsynchronized, that is, if two tasks call
   -- TRANSMIT at the same time, or two tasks call RECEIVE at the
   -- same time, the stream state will get screwed up.  Don't.


   TYPE Pool_Id IS PRIVATE;

   FUNCTION Create (Network       : Transport_Defs.Network_Name;
                    Remote_Host   : Transport_Defs.Host_Id;
                    Remote_Socket : Transport_Defs.Socket_Id;
                    Local_Socket  : Transport_Defs.Socket_Id :=
                       Transport_Defs.Null_Socket_Id) RETURN Pool_Id;

   -- Create a pool of active streams.


   PROCEDURE Destroy (Pool : Pool_Id);

   -- Disconnect all streams in the pool,
   -- and terminate all associated tasks.


   PROCEDURE Allocate
                (Stream : OUT Stream_Id; Pool : Pool_Id; Is_New : OUT Boolean);

   -- Get an idle stream from the pool.  If no idle stream
   -- is available, create one, open and connect a
   -- transport connection, and return IS_NEW = TRUE.
   -- If this fails, raise NOT_CONNECTED.


   PROCEDURE Scavenge (Pool : Pool_Id);

   -- Disconnect any streams which have been deallocated
   -- for a while.


   PROCEDURE Scavenge;

   -- Scavenge all pools.
   -- This procedure is called periodically (every minute)
   -- by a scavenger task inside the service.


   PROCEDURE Finalize;

   -- Destroy all pools, and terminate all tasks.


   -- Like all pools with explicit allocate and deallocate
   -- operations, this service is vulnerable to clients
   -- which allocate a resource and then fail to deallocate
   -- it, e.g. because they terminate abnormally.  This
   -- problem isn't easily solved in standard Ada.  If your
   -- system has some way of dealing with it, you might
   -- consider extending this service to do the right thing.

PRIVATE

   TYPE Pool_Type (Network_Length       : Natural;
                   Remote_Host_Length   : Natural;
                   Remote_Socket_Length : Natural;
                   Local_Socket_Length  : Natural);

   TYPE Pool_List IS ACCESS Pool_Type;

   TYPE Pool_Id IS NEW Pool_List;

   TYPE Stream_Type;

   TYPE Stream_List IS ACCESS Stream_Type;

   TYPE Pool_Type (Network_Length       : Natural;
                   Remote_Host_Length   : Natural;
                   Remote_Socket_Length : Natural;
                   Local_Socket_Length  : Natural) IS
      RECORD
         Next          : Pool_List;
         Idle          : Stream_List;
         Network       : Transport_Defs.Network_Name (1 .. Network_Length);
         Remote_Host   : Transport_Defs.Host_Id (1 .. Remote_Host_Length);
         Remote_Socket : Transport_Defs.Socket_Id (1 .. Remote_Socket_Length);
         Local_Socket  : Transport_Defs.Socket_Id (1 .. Local_Socket_Length);
      END RECORD;



   SUBTYPE Unique_Id IS Integer;

   Null_Unique_Id : CONSTANT Unique_Id := Unique_Id'First;

   TYPE Stream_Id IS
      RECORD
         Stream : Stream_List;
         Unique : Unique_Id;
      END RECORD;

   Buffer_Size : CONSTANT := 2 ** 10;


   SUBTYPE Data_Count IS Natural RANGE 0 .. Buffer_Size;

   SUBTYPE Data_Index IS Data_Count RANGE 0 .. Data_Count'Last - 1;

   TYPE Buffer_Type IS
      RECORD
         First : Data_Index;
         Count : Data_Count;
         Data  : Byte_Defs.Byte_String (Data_Index'First .. Data_Index'Last);
      END RECORD;

   TYPE Stream_Type IS
      RECORD
         Next              : Stream_List := NULL;
         Pool              : Pool_Id     := NULL;
         Unique            : Unique_Id   := Null_Unique_Id;
         Referenced        : Boolean     := False;
         Connection        : Transport.Connection_Id;
         Transmit, Receive : Buffer_Type;
      END RECORD;


END Transport_Stream;
DataMuseum.dk

Rational R1000/400 Tapes

⟦9d5fb3f95⟧ TextFile

Derivation

TextFile
