Description
Launch, protocol, application, or image-lifecycle operation failed.
Begin_Canary
procedure Begin_Canary
(Item : in out Coordinator;
Authority : Upgrade_Handle;
Timeout : Duration := 30.0;
Token : access Flyology.Cancellation.Token := null)
Start candidate admission and wait for exact accepting/topology proof.
Parameters
- Item
Coordinator holding the prepared candidate
- Authority
Exact current transaction authority
- Timeout
Total activation and readiness timeout
- Token
Optional one-shot cancellation source
Cancel
procedure Cancel
(Item : in out Coordinator;
Authority : Upgrade_Handle;
Compensation : out Compensation_Result;
Timeout : Duration := 30.0)
Revoke and drain a prepared or canary candidate. During a canary the compensation hook runs after quiescence. The active image is untouched.
Parameters
- Item
Coordinator holding the candidate
- Authority
Exact current transaction authority
- Compensation
Observed application compensation outcome
- Timeout
Total cancellation timeout
Coordinator
type Coordinator is new Ada.Finalization.Limited_Controlled with private;
Stable owner of listener escrow and managed image slots.
Coordinator_Snapshot
type Coordinator_Snapshot is record
Initialized : Boolean := False;
Phase : Upgrade_Phase := Stable;
Authority : Upgrade_Handle := (Coordinator => 1, Upgrade => 1, Candidate => 1);
Has_Active : Boolean := False;
Active_Generation : Image_Generation := 1;
Has_Candidate : Boolean := False;
Candidate_Generation : Image_Generation := 1;
Candidate_Ready : Boolean := False;
Candidate_Admitted : Boolean := False;
Rollback_Available : Boolean := False;
Desired_Topology_Epoch : Messages.Nonzero_U64 := 1;
Desired_Topology_Digest : Messages.Topology_Digest := (others => 0);
Compensation : Compensation_Result := Not_Required;
Failure_Size : Failure_Length := 0;
Failure : Failure_Buffer := (others => ' ');
end record;
Point-in-time observation of coordinator state.
Record fields
- Initialized
Listener escrow and identity are initialized
- Phase
Current transaction phase
- Authority
Current or most recently completed authority
- Has_Active
An active image slot is occupied
- Active_Generation
Active image generation when present
- Has_Candidate
A candidate image slot is occupied
- Candidate_Generation
Candidate generation when present
- Candidate_Ready
Candidate supplied matching readiness evidence
- Candidate_Admitted
Candidate can accept new connections
- Rollback_Available
A previous artifact can be restarted fresh
- Desired_Topology_Epoch
Desired topology epoch
- Desired_Topology_Digest
Desired topology digest
- Compensation
Latest cancellation compensation observation
- Failure_Size
Significant bytes in Failure
- Failure
Fixed storage for the latest bounded failure message
Failure_Buffer
type Failure_Buffer is array (Positive range 1 .. Maximum_Failure_Length) of Character;
Fixed storage for a bounded failure message.
Failure_Length
subtype Failure_Length is Natural range 0 .. Maximum_Failure_Length;
Significant retained failure-message length.
Failure_Message
function Failure_Message (Item : Coordinator_Snapshot) return String
Extract the significant retained failure text.
Parameters
- Item
Coordinator snapshot
Return value
Failure text, or an empty string when no failure is retained
Identity_Exhausted
Identity_Exhausted : exception;
A nonwrapping upgrade or generation identifier is exhausted.
Initialize
procedure Initialize
(Item : in out Coordinator;
Identity : Coordinator_Id;
Listener : in out Flyology.IO.Sockets.Socket_Type;
First_Upgrade : Upgrade_Id := 1;
First_Generation : Image_Generation := 1)
Transfer a bound listening socket into stable coordinator escrow.
Parameters
- Item
Uninitialized coordinator
- Identity
Stable nonzero coordinator identity
- Listener
Bound listener whose ownership is transferred
- First_Upgrade
First nonwrapping transaction identity
- First_Generation
First nonwrapping process-generation identity
Invalid_Phase
Invalid_Phase : exception;
Requested operation is not valid in the current lifecycle phase.
Maximum_Failure_Length
Maximum_Failure_Length : constant Positive := 256;
Maximum retained failure-message size.
Promote
procedure Promote (Item : in out Coordinator; Authority : Upgrade_Handle; Timeout : Duration := 30.0)
Commit the candidate, then drain and reap the previous active image. Any failure after this call begins is classified Rollback_Required.
Parameters
- Item
Coordinator holding the ready candidate
- Authority
Exact current transaction authority
- Timeout
Total promotion and previous-image drain timeout
Rollback_To_Previous
procedure Rollback_To_Previous
(Item : in out Coordinator; Authority : out Upgrade_Handle; Timeout : Duration := 30.0)
Retire every image implicated in a completed or uncertain promotion, then start a fresh process from the retained previous artifact and topology. No old Ada runtime, task, or connection is resurrected.
Parameters
- Item
Coordinator with a retained previous artifact
- Authority
Newly allocated rollback transaction authority
- Timeout
Total fencing and fresh-image startup timeout
Shutdown
procedure Shutdown (Item : in out Coordinator; Timeout : Duration := 30.0)
Cleanly drain every managed image when possible, then release listener escrow. Cleanup failures are reported after all slots are attempted.
Parameters
- Item
Coordinator to shut down
- Timeout
Total drain timeout for each managed image
Snapshot
function Snapshot (Item : in out Coordinator) return Coordinator_Snapshot
Capture current coordinator state. The observation reconciles and reaps any managed image whose terminal process state is already available.
Parameters
- Item
Initialized coordinator
Return value
Point-in-time state observation
Stale_Authority
Stale_Authority : exception;
Supplied transaction authority does not match the active upgrade.
Start_Initial
procedure Start_Initial
(Item : in out Coordinator;
Executable : Flyology.Subprocesses.Command;
Provision : Messages.Provisioning_Data;
Authority : out Upgrade_Handle;
Timeout : Duration := 30.0;
Token : access Flyology.Cancellation.Token := null)
Convenience for bootstrapping the first managed active image.
Parameters
- Item
Initialized coordinator with no active image
- Executable
Initial executable and launch context
- Provision
Desired topology and active role
- Authority
Newly allocated initial transaction authority
- Timeout
Total startup, readiness, and promotion timeout
- Token
Optional one-shot cancellation source
Start_Upgrade
procedure Start_Upgrade
(Item : in out Coordinator;
Executable : Flyology.Subprocesses.Command;
Provision : Messages.Provisioning_Data;
Authority : out Upgrade_Handle;
Timeout : Duration := 30.0;
Token : access Flyology.Cancellation.Token := null)
Spawn, authenticate, provision, and hand a borrowed listener duplicate to a candidate. The server is not started and cannot accept on return.
Parameters
- Item
Initialized coordinator with no candidate
- Executable
Candidate executable and launch context
- Provision
Desired topology and candidate role
- Authority
Newly allocated transaction authority
- Timeout
Total startup and provisioning timeout
- Token
Optional one-shot cancellation source
Upgrade_Error
Upgrade_Error : exception;
Launch, protocol, application, or image-lifecycle operation failed.