⟦441ec77da⟧

TextFile

with Calendar;
with Machine;

package Disk_Daemon is
    pragma Subsystem (Disk_Cleaner);
    pragma Module_Name (4, 3401);

    subtype Volume_Number is Integer range 0 .. 31;
    subtype Task_Vpids    is Machine.Job_Id;

    -- The procedural operations of this package are noops when given
    -- invalid parameters (out of range, volume does not exist, ...).
    -- The functions return 'first when given invalid parameters.

    type Threshold_Kinds is
       (Start_Collection,    -- Default 25%; start collection on this volume.
        Raise_Priority,      -- Default 15%; raise priority of all collection
        --     until this volume gets above this threshold.
        Stop_Jobs,           -- Default 10%; stop user jobs and max priority
        --     until this volume gets above this threshold.
        Suspend_System);     -- Default 3%; suspend the system.

    subtype Percentage is Natural range 0 .. 100;

    function Exists (Volume : Volume_Number) return Boolean;

    procedure Set_Threshold (Volume                : Volume_Number;
                             Kind                  : Threshold_Kinds;
                             At_Remaining_Capacity : Percentage);
    function  Get_Threshold (Volume : Volume_Number; Kind : Threshold_Kinds)
                           return Percentage;

    function Capacity        (Volume : Volume_Number) return Natural;
    function Used_Capacity   (Volume : Volume_Number) return Natural;
    function Unused_Capacity (Volume : Volume_Number) return Natural;

    -- The capacity functions return the size in number of 1024 byte pages.

    subtype Collection_Priority is Integer range -1 .. 6;

    -- -1 => Attempts to collect using just "spare cpu cycles"; if there are
    --       no spare cycles, will wait forever (or until some agent increases
    --       the priority).
    --
    --  0 => Slowest priority without backoff; runs on par with background jobs
    --       that do not use 'priority.  Small impact on performance.
    --
    --  2 => Will preempt most background jobs.  Runs on par with a background
    --       job that uses the best 'priority.
    --
    --  3 => Runs on par with most foreground jobs.  Tends to have a big impact
    --       on performance, since it will compete with commands.
    --
    --  4 => Preempts most foreground jobs.  Should still be able to edit.
    --       But commands will run VERY slowly.
    --
    --  6 => Preempts virtually all activity, except that from the console.

    -- Note that there is a policy function which places a lower bound on the
    -- current collection priority.  See the Set_Priority_Policy operation,
    -- below.

    procedure Perform_Garbage_Collection
                 (Volume                  :     Volume_Number;
                  Max_Wait                :     Duration;
                  Desired_Priority        :     Collection_Priority := 0;
                  This_Call_Did_A_Gc_Pass : out Boolean);

    -- Causes a garbage collection pass on the specified volume.  Caller will
    -- wait for at most MAX_WAIT seconds for the garbage collection pass to
    -- begin.  (A low space condition will cause garbage collection to happen
    -- automatically.)  If this call starts a garbage collection pass, then
    -- This_Call_Did_A_Gc_Pass will be returned true, and the caller will wait
    -- until the pass is completed  (a potentially long time, since that
    -- involves lots of work).

    -- The garbage collection pass will be executed at the better of the
    -- specified collection priority and that determined by the priority
    -- policy function, defined below (with the Set_Priority_Policy
    -- operation).

    -- There is only 1 worker task.  This serializes garbage collection to
    -- help prevent anamolous situations in which the garbage collector runs
    -- for extraordinarily long periods of time.

    generic
        with procedure Put_Line (S : String);
    procedure Display_Current_Gc_State;

    -- Displays various pieces of gc state.

    function Garbage_Collector_Is_Running
                (Volume : Volume_Number) return Boolean;

    -- Returns true iff the garbage collector is running on the specified
    -- volume.

    function Garbage_Collector_Is_Running return Boolean;

    -- Returns true iff the garbage collector is running.

    function Jobs_Are_Stopped_By_Volume (Volume : Volume_Number) return Boolean;

    -- Returns true iff all jobs were stopped because the specified Volume
    -- reached the warning threshold.

    function Jobs_Are_Stopped return Boolean;

    -- Returns true iff all jobs were stopped because some volume reached the
    -- warning threshold.

    function Start_Time return Calendar.Time;
    -- Returns 'first when gc is not running.

    type Collection_Phase is (Idle, Waiting_For_Backup_To_Finish,
                              Taking_Snapshot, Deleting_Segments,
                              Traversing_Virtual_Memory, Reclaiming_Blocks);

    function Current_Phase return Collection_Phase;
    -- Returns Idle when gc is not running.

    function Current_Priority (Volume : Volume_Number)
                              return Collection_Priority;

    -- If the Volume does not exist, or the garbage collector for that volume
    -- has never run, returns worst priority (-1).  If the garbage collector is
    -- currently running, returns the value that it is running at; otherwise
    -- returns the value it last ran at.

    procedure Set_Current_Priority (Volume           : Volume_Number;
                                    Desired_Priority : Collection_Priority);

    -- If the garbage collector is currently running in the
    -- Traversing_Virtual_Memory phase, this operation will change the rate
    -- at which its running, otherwise has no effect.

    -- Note that there is a policy function that places a lower bound on the
    -- current collection priority.  (See the Set_Priority_Policy operation,
    -- below.)  If the specified priority is below that specified by the
    -- priority policy, the Set_Current_Priority operation is a noop.

    function Reclaimed_Segments return Natural;

    -- Returns the number of segments which were deleted by gc.
    -- These values are set to 0 when gc starts.  Don't expect them to
    -- become non-zero until Current_Phase is >= Deleting_Segments.

    function Visited_Segments    return Natural;
    function Visited_Blocks      return Natural;
    function Time_Spent_Delaying return Duration;

    -- The first 2 functions return the number of segments/blocks which have
    -- been "visited" by the virtual memory traversal.  The 3rd function
    -- returns an approximate value for how much time gc has spent backing off,
    -- as a result of the load parameters.  These values are set to 0 when
    -- gc starts.  Don't expect them to become non-zero until Current_Phase is
    -- >= Traversing_Virtual_Memory.

    function  Stop_Run_Load return Natural;  -- default: 250
    procedure Set_Stop_Run_Load (Run_Load : Natural);

    function  Stop_Withheld_Load return Natural;  -- default: 1
    procedure Set_Stop_Withheld_Load (Withheld_Load : Natural);

    function  Start_Run_Load return Natural;  -- default: 125
    procedure Set_Start_Run_Load (Run_Load : Natural);

    function  Start_Withheld_Load return Natural;  -- 0
    procedure Set_Start_Withheld_Load (Withheld_Load : Natural);

    procedure Use_Standard_Backoff_Algorithm;

    -- During the Traversing_Virtual_Memory phase,the collector follows
    -- roughly the following algorithm:
    --    loop
    --        do about 500 milliseconds of work, and a few disk accesses
    --        if (Run_Load > Stop_Run_Load) or
    --           (Withheld_Load > Stop_Withheld_Load) then
    --            loop
    --                delay 30.0; -- seconds
    --                exit when (Run_Load < Start_Run_Load) and
    --                          (Withheld_Load < Start_Withheld_Load);
    --            end loop;
    --        end if;
    --    end loop;
    -- The loads for the stop tests are sampled over the last minute.  The
    -- load for the restart tests are sampled over the last 5 minutes.

    -- The values supplied to the Set_ operations should be MTS loads,
    -- multiplied by 100. For example, 125 means an MTS load of 1.25.

    -- The Use_Standard_Backoff_Algorithm procedure will revert the collector
    -- to using its built in backoff algorithm.

    function  Footprinting_Enabled return Boolean;
    procedure Set_Footprinting (Desired_Value : Boolean);

    -- When the system boots, footprinting is disabled. True means footprinting
    -- is enabled.  When footprinting is enabled, reclaimed disk blocks are
    -- cleared.  This lengthens the amount of time spent in the
    -- Reclaiming_Blocks phase, since 1 disk I/O is required for every
    -- block reclaimed.

    function  Backup_Killing_Enabled return Boolean;
    procedure Set_Backup_Killing (Desired_Value : Boolean);

    -- When the system boots, backup kill mode is enabled.  True means to
    -- enable backup kill mode.  In backup kill mode, if the garbage collector
    -- is caused to run (via any method, including direct call, daemon
    -- scheduling, or disk space thresholds) and a backup is in progress,
    -- the backup will be terminated.  Recall that this whole issue stems
    -- from the fact that the garbage collection mechanisms don't work in
    -- the case where backup has a retained snapshot which is earlier than
    -- the retained snapshot which the garbage collector is using.

    function  Prevent_Stop_By_Warning     (Job : Task_Vpids) return Boolean;
    procedure Set_Prevent_Stop_By_Warning (Desired_Value : Boolean);

    -- This mechanism allows individual jobs to prevent themselves from being
    -- stopped when the garbage collector reaches the warning threshold (and
    -- stops all jobs). By default, jobs 4 & 5 are registered as not being
    -- stopped; otherwise the compaction daemons (such as DDB) and the gc can
    -- get deadlocked. This mechanism is also used by backup to prevent a
    -- deadlock.


    function  Get_Priority_Policy
                (Raised_Count : Integer; Started_Count : Integer)
                return Collection_Priority;
    procedure Set_Priority_Policy (Raised_Count     : Integer;
                                   Started_Count    : Integer;
                                   Desired_Priority : Collection_Priority);

    -- There is a policy function which specifies the minimum allowable
    -- collection priority as a function of the number of volumes which have
    -- reached the Start_Collection threshold and the number of volumes which
    -- have reached the Raise_Priority threshold.  The default policy is:

    -- If there are 0 volumes past the Raise_Priority threshold, then the
    -- priority policy is the following function of the number of volumes
    -- past the Start_Collection threshold:
    --             1 volume  => Collection_Priority'(-1)
    --             2 volumes =>                       0
    --             3 volumes =>                       1
    -- For all remaining combinations, the policy is Collection_Priority'(2).

    -- The default policy is intended to have the following properties:
    -- When just a single volume wants to collect, let it run using
    -- spare cycles.  When more than one volume wants to collect, stop
    -- backing off.  When any Raise_Priority threshold is reached,
    -- raise priority such that the collection will preempt most background
    -- jobs.

    -- The set operation allows you to define your own priority policy. Hints
    -- for "rolling your own": (1) Setting the policy to return -1 for all
    -- inputs effectively disables the policy altogether. (2) The default
    -- policy does not increase the priority to 3 on the assumption that
    -- either (a) the mts parameters in effect limit the length of time an
    -- attached job can remain in the foreground or (b) that people do not
    -- typically leave attached jobs run for long periods of time. (3)
    -- Creating a policy which increases the priority to 5 or greater will
    -- probably have roughly the same impact as reaching the Stop_Jobs
    -- threshold.

end Disk_Daemon;
DataMuseum.dk

Rational R1000/400 Tapes

⟦441ec77da⟧ TextFile

Derivation

TextFile
