DataMuseum.dk

top - download

    Length: 4674 (0x1242)
    Types: TextFile
    Names: »V«

└─⟦bad92a95e⟧ Bits:30000535 8mm tape, Rational 1000, RPC 1_0_2
    └─ ⟦bb34fe6e2⟧ »DATA« 
        └─⟦15d8b76c6⟧ 
            └─⟦this⟧ 

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;

    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;

end Transport_Stream;