⟦c1a203391⟧

E3 Source Code



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.

    pragma Subsystem (Network, Private_Part => Closed);
    pragma Module_Name (4, 2515);


    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.

    function Connection (Stream : Stream_Id) return Transport.Connection_Id;

    subtype Unique_Id is Integer;

    function Unique (Stream : Stream_Id) return Unique_Id;


    procedure Set_User_Id (Stream : Stream_Id; User_Id : Integer := 0);
    function  Get_User_Id (Stream : Stream_Id) return Integer;

    -- This package keeps a map from Stream_Id to integer,
    -- which you can set and query using these subprograms.
    -- The User_Id is initialized to 0 when Is_New := True.
    -- The User_Id is not used by Transport_Stream: it is
    -- provided so that clients can associate higher level
    -- information with each stream.  For example, RPC uses
    -- it to record the RPC protocol version in use on the
    -- stream.

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;


    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;
DataMuseum.dk

Rational R1000/400

⟦c1a203391⟧ Ada Source

Derivation

E3 Source Code

E3 Meta Data
