DataMuseum.dk

Presents historical artifacts from the history of:

Rational R1000/400 Tapes

This is an automatic "excavation" of a thematic subset of
artifacts from Datamuseum.dk's BitArchive.

See our Wiki for more about Rational R1000/400 Tapes

Excavated with: AutoArchaeologist - Free & Open Source Software.


top - download
Index: ┃ T V

⟦81c2eb6c4⟧ TextFile

    Length: 12216 (0x2fb8)
    Types: TextFile
    Names: »V«

Derivation

└─⟦d10a02448⟧ Bits:30000409 8mm tape, Rational 1000, ENVIRONMENT, D_12_7_3
    └─ ⟦fc9b38f02⟧ »DATA« 
        └─⟦9b46a407a⟧ 
            └─⟦c84a2ac9b⟧ 
                └─⟦this⟧ 

TextFile

with Action;
with Ada_Program;
with Directory;
with Errors;
package Element_Cache is

    subtype Element      is Ada_Program.Element;
    subtype Element_List is Ada_Program.Element_List;

    type Handle is limited private;
    type Modes  is (Create, Read, Update);


    --------------------------
    -- Old Style Interfaces --
    --------------------------

    -- These interfaces are obsolete and their use is discouraged.  The
    -- preferred interfaces are declared below function Debug_Image.

    procedure Open (Cache : in out Handle;  
                    Mode  :        Modes;  
                    Name  :        String);

    procedure Close (Cache : in out Handle);

    procedure Destroy (Cache : in out Handle);


    subtype Key is String;

    procedure Add (An_Element :        Element;  
                   To_Cache   : in out Handle;
                   With_Key   :        Key);

    procedure Remove (An_Element :        Element;  
                      From_Cache : in out Handle;
                      With_Key   :        Key);


    procedure Add (An_Element_List :        Element_List;  
                   To_Cache        : in out Handle;
                   With_Key        :        Key);

    procedure Remove (An_Element_List :        Element_List;
                      From_Cache      : in out Handle;
                      With_Key        :        Key);


    procedure Retrieve (Elements   : out Element_List;
                        From_Cache :     Handle;
                        With_Key   :     Key;
                        In_Context :     String := "<DEFAULT>");
    --
    -- This operation does not raise FAILED when errors are detected
    -- during the retrieval of ELEMENTS from FROM_CACHE.  Instead, as
    -- many valid elements as possible are retieved and placed in
    -- ELEMENTS.  When the complete success of the retrieval operation
    -- must be known, STATUS and DIAGNOSIS can be queried after the call
    -- to RETRIVE in order to determine if any problems were encountered
    -- during the operation.


    Failed : exception;
    --
    -- FAILED is raised when any of the above operations
    -- cannot be successfully completed.  STATUS and DIAGNOSIS
    -- may be used to obtain additional information about the
    -- nature of the failure.

    function Diagnosis return String;
    function Status    return Errors.Condition;


    function Debug_Image (Of_Handle       : Handle;
                          Level           : Natural;
                          Prefix          : String;
                          Expand_Pointers : Boolean) return String;


    --------------------------
    -- Preferred Interfaces --
    --------------------------

    -- The following subprograms provide the same functionality as their
    -- overloaded counterparts above, except that these subprograms
    -- provide a STATUS parameter where appropriate and generally do not
    -- raise the FAILED exception.

    procedure Open (Cache     : in out Handle;  
                    Mode      :        Modes;  
                    Name      :        String;
                    Status    : in out Errors.Condition;
                    Action_Id :        Action.Id := Action.Null_Id);
    --
    -- When ACTION_ID = ACTION.NULL_ID, an action managed by the
    -- job is used by the open, and is finished as appropriate at
    -- the end of the job.  When ACTION_ID /= ACTION.NULL_ID,
    -- ACTION_ID is used in subsequent operations and should be
    -- finished by the client which started it.

    procedure Close (Cache  : in out Handle;  
                     Status : in out Errors.Condition);

    procedure Destroy (Cache  : in out Handle;  
                       Status : in out Errors.Condition);


    type Storage_Formats is (Fully_Qualified,  
                             Subsystem_Relative,  
                             View_Relative);
    --
    -- Type STORAGE_FORMATS determines how elements are
    -- represented in the cache.  The permanent representation
    -- used in the caches is equivalent to that provided in the
    -- Ada_Program.Conversion.Convert operations.  A summary of
    -- the storage formats is provided below.
    --
    --  FULLY_QUALIFIED    => The element's fully qualified resolution
    --                        is stored.  This format is useful for
    --                        elements from non-subsystem contexts or
    --                        when subsystem/view information must be
    --                        saved.
    --
    --  SUBSYSTEM_RELATIVE => The resolution of the element is subsystem
    --                        relative.  The subsystem name along with
    --                        an SPEC/LOAD view indication are stored.
    --                        This format is useful for elements in
    --                        subystem contexts when retreival is desired
    --                        in a potentially different view context.  See
    --                        the IN_CONTEXT parameter on procedure RETRIEVE
    --                        below.
    --
    --  VIEW_RELATIVE      => The resolution of the element is completely
    --                        view relative.  No subsystem or SPEC/LOAD
    --                        indication is stored.  This format is useful
    --                        for elements in subsystem contexts which will
    --                        ALWAYS be retrieved in a particular
    --                        subsystem/view pair.

    procedure Add (An_Element :        Element;  
                   To_Cache   : in out Handle;
                   With_Key   :        Key;
                   Status     : in out Errors.Condition;
                   Format     :        Storage_Formats :=
                      Element_Cache.Subsystem_Relative);
    --
    -- Stores AN_ELEMENT in TO_CACHE under WITH_KEY in FORMAT
    -- representation.  If AN_ELEMENT was previously ADD'ed
    -- with the same parameters, this operation is a no-op.
    -- When a single element is ADD'ed to the same cache with
    -- different values for the FORMAT parameter, separate
    -- entries for each given format are stored.
    --
    -- NOTE: In order to REMOVE a given element from the cache,
    -- the same values for WITH_KEY and FORMAT must be provided.

    procedure Remove (An_Element :        Element;  
                      From_Cache : in out Handle;
                      With_Key   :        Key;
                      Status     : in out Errors.Condition;
                      Format     :        Storage_Formats :=  
                         Element_Cache.Subsystem_Relative);
    --
    -- Removes AN_ELEMENT stored under WITH_KEY from FROM_CACHE in
    -- FORMAT representation.  When AN_ELEMENT is not stored under
    -- WITH_KEY in the specified FORMAT, UNDEFINED_ELEMENT is returned
    -- in STATUS.  When WITH_KEY is not defined in FROM_CACHE,
    -- UNDEFINED_KEY is returned in STATUS.


    procedure Add (An_Element_List :        Element_List;  
                   To_Cache        : in out Handle;
                   With_Key        :        Key;
                   Status          : in out Errors.Condition;
                   Format          :        Storage_Formats :=
                      Element_Cache.Subsystem_Relative);
    --
    -- Equivalent to single element ADD as defined above on each
    -- element in AN_ELEMENT_LIST.

    procedure Remove (An_Element_List :        Element_List;
                      From_Cache      : in out Handle;
                      With_Key        :        Key;
                      Status          : in out Errors.Condition;
                      Format          :        Storage_Formats :=  
                         Element_Cache.Subsystem_Relative);
    --
    -- Equivalent to single element REMOVE as defined above on each
    -- element in AN_ELEMENT_LIST.


    procedure Retrieve (Elements   : out    Element_List;
                        From_Cache :        Handle;
                        With_Key   :        Key;
                        Status     : in out Errors.Condition;
                        Format     :        Storage_Formats :=  
                           Element_Cache.Subsystem_Relative;
                        In_Context :        String          := "<DEFAULT>");
    --
    -- Restores the ELEMENTS that were saved in FROM_CACHE under
    -- WITH_KEY in FORMAT representation.  The IN_CONTEXT parameter
    -- determines how the resolution of saved elements will be
    -- performed.  In all cases, if the elements were saved in
    -- FULLY_QUALIFED format this parameter is ignored.  Otherwise, the
    -- following algorithm is followed.
    --
    --  <DEFAULT>      => For elements saved in SUBSYSTEM_RELATIVE format,
    --                    the view selected by the current activity and
    --                    the stored subsystem is used as the origin. The
    --                    spec or load origin of the representation is
    --                    used to choose the specific view.  For elements
    --                    saved in VIEW_RELATIVE format, the current view
    --                    context is used as the origin.
    --
    --  Subsystem Name => For elements saved in SUBSYSTEM_RELATIVE format,
    --                    this behaves the same as <DEFAULT>.  For elements
    --                    saved in VIEW_RELATIVE format, the view selected
    --                    by the current activity for the given subsystem
    --                    is used.  The subsystem name can be followed by
    --                    "'SPEC" or "'LOAD" to force use of the spec view
    --                    or load view from the activity; DEFAULT: Spec View
    --
    --  View Name      => For elements saved in SUBSYSTEM_RELATIVE format,
    --                    if the subsystem enclosing the given view name
    --                    matches the representation's subsystem, the
    --                    given view is used.  Otherwise, this behaves
    --                    the same as <DEFAULT>.  For elements saved in
    --                    VIEW_RELATIVE format the specified view is used.


    ----------------------
    -- Cache Compaction --
    ----------------------

    procedure Compactify (The_Cache : in out Handle;
                          Status    : in out Errors.Condition);
    --
    -- Reorganizes cache data structures into a more optimal format.
    --   Assert => MODE (THE_CACHE) /= READ.


    --------------------------
    -- Cache Handle Queries --
    --------------------------

    function Is_Open (Cache : Handle) return Boolean;

    function Mode (Of_Cache : Handle) return Modes;
    --
    -- Raises FAILED when not IS_OPEN (OF_CACHE)

    function Name (Of_Cache : Handle) return String;
    --
    -- Raises FAILED when not IS_OPEN (OF_CACHE)

    function Object_Id (Of_Cache : Handle) return Directory.Object;
    --
    -- Raises FAILED when not IS_OPEN (OF_CACHE)


    -------------------
    -- Key Iterators --
    -------------------

    -- The following type and operations provide a means of
    -- iterating over the set of keys defined for a given cache.

    type Key_Iterator is private;

    procedure Initialize (Iterator   : in out Key_Iterator;  
                          From_Cache :        Handle);
    function  Done       (Iterator : Key_Iterator)    return Boolean;
    function  Value      (Of_Iterator : Key_Iterator) return Key;
    procedure Next       (The_Iterator : in out Key_Iterator);


    ------------------------------
    -- Predefined Status Values --
    ------------------------------

    Undefined_Element : constant Errors.Error_Kinds :=  
       Errors.Make ("UNDEFINED_ELEMENT", Errors.Warn);
    Undefined_Key     : constant Errors.Error_Kinds :=  
       Errors.Make ("UNDEFINED_KEY", Errors.Warn);


    pragma Subsystem (Design_Facility, Closed);
    pragma Module_Name (4, 3593);
    pragma Bias_Key (27);

private

    type Handle_Data;
    type Handle is access Handle_Data;
    pragma Segmented_Heap (Handle);

    type Key_Data;
    type Key_Iterator is access Key_Data;
    pragma Segmented_Heap (Key_Iterator);

end Element_Cache;