Description
Selects and observes event-loop execution groups for lightweight tasks.
Example:
Flyology.Execution_Groups.Migrate (1);
Automatic_Placement_Policy
type Automatic_Placement_Policy is (Round_Robin);
Automatic assignment policy for tasks without a CPU aspect.
Enumeration literals
- Round_Robin
Select successive groups in the configured pool
Configure_Loop_Thread
function Configure_Loop_Thread
(Group : Group_Id;
Kind : Loop_Thread_Placement;
Value : Placement_Value := 0) return Placement_Configuration_Result
Configure a scheduler thread before Group starts. The same request is idempotent after startup; changing or clearing it then reports Group_Already_Started. Strict_CPU is a Linux OS CPU in the process's allowed set. Advisory_Tag must be positive. No_Placement requires zero.
Parameters
- Group
Execution group whose scheduler thread is configured
- Kind
Host placement mechanism
- Value
Linux logical CPU, Darwin advisory tag, or zero
Return value
Explicit configuration result; this starts no group
Raised exceptions
- Group_Error
The runtime returns an unknown result
Configured_Placement
function Configured_Placement return Automatic_Placement_Policy
Return the automatic policy without starting any group.
Return value
Configured placement policy
Raised exceptions
- Group_Error
The runtime reports an unknown policy
Configured_Pool_Size
function Configured_Pool_Size return Loop_Pool_Size
Return the automatic pool size without starting any group. A lightweight task without a specific CPU is assigned among groups 0 .. Result - 1.
Return value
Configured shared-group pool size
Raised exceptions
- Group_Error
The runtime reports an invalid size
Create_Dedicated
function Create_Dedicated return Dedicated_Group_Id
Reserve an empty reusable dedicated group for the calling lightweight task. Migrating out consumes the reservation; call Create_Dedicated again before re-entering a dedicated group. The same id is normally reused.
Return value
Reserved group in 128 .. 255
Raised exceptions
- Group_Error
The caller is native or no group can be reserved
Current
function Current return Group_Id
Return the calling lightweight task's current execution group.
Return value
Current group identifier
Raised exceptions
- Group_Error
The caller is native or runtime result is invalid
Current_Processor
function Current_Processor return Integer
Return the calling thread's current logical processor where the host provides a stable public query (Linux), otherwise No_Processor.
Return value
Current zero-based logical CPU or No_Processor
Dedicated_Group_Id
subtype Dedicated_Group_Id is Group_Id range 128 .. Group_Id'Last;
Exclusively reserved groups returned by Create_Dedicated.
Default_Group
Default_Group : constant Shared_Group_Id := 0;
First shared group.
For_CPU
function For_CPU
(CPU : System.Multiprocessors.CPU_Range) return Shared_Group_Id
Convert an Ada CPU value in 0 .. 127 to its shared Flyology group.
Parameters
- CPU
Ada CPU aspect value
Return value
Shared group with the same numeric value
Group_Error
Group_Error : exception;
Raised when a group query, reservation, or pin operation cannot complete.
Group_Id
type Group_Id is range 0 .. 255;
Identifier of one permanent event-loop execution group.
In_Configured_Pool
function In_Configured_Pool (Group : Group_Id) return Boolean
Test membership in the automatic pool without starting a group.
Parameters
- Group
Group to test
Return value
True when Group is below Configured_Pool_Size
Raised exceptions
- Group_Error
The runtime reports an invalid pool size
Is_Dedicated
function Is_Dedicated (Group : Group_Id) return Boolean
Test the numeric group class; this starts no group.
Parameters
- Group
Group identifier to classify
Return value
True for groups 128 .. 255
Is_Thread_Pinned
function Is_Thread_Pinned return Boolean
Report whether the caller is pinned. Native tasks always report True.
Return value
True for a native task or a lightweight task with a live pin
Loop_Pool_Size
subtype Loop_Pool_Size is Positive range 1 .. 128;
Number of shared groups participating in automatic placement.
Loop_Thread_Placement
type Loop_Thread_Placement is
(No_Placement, Strict_CPU, Advisory_Tag);
Optional placement of an execution group's scheduler thread. This is independent from an Ada CPU aspect, which selects an execution group.
Enumeration literals
- No_Placement
Do not request host placement
- Strict_CPU
Bind to one Linux logical CPU; unsupported on Darwin
- Advisory_Tag
Apply a Darwin cache-locality tag, not a CPU number
Loop_Thread_Status
function Loop_Thread_Status (Group : Group_Id) return Placement_Status
Observe Group's placement request without starting it.
Parameters
- Group
Execution group to inspect
Return value
Current placement status
Raised exceptions
- Group_Error
The runtime query or returned encoding is invalid
Migrate
procedure Migrate (Group : Group_Id)
Migrate the calling lightweight task at this cooperative safe point and return on Group's scheduler thread. A live Thread_Pin prevents movement to another group. Native tasks cannot migrate because GNARL owns their stacks and threads. Leaving a dedicated group consumes its reservation.
Parameters
- Group
Destination execution group
Raised exceptions
- Migration_Error
Caller is native, pinned, or cannot enter Group
Migration_Error
Migration_Error : exception;
Raised when the calling task cannot migrate to the requested group.
No_Processor
No_Processor : constant Integer := -1;
Current_Processor result when no supported stable query exists.
Pin_To_Current_Thread
function Pin_To_Current_Thread return Thread_Pin
Acquire one pin level for the calling task.
Return value
Task-owned guard that releases the pin during finalization
Raised exceptions
- Group_Error
The runtime cannot pin the caller
Placement_Configuration_Result
type Placement_Configuration_Result is
(Configured,
Unchanged,
Unsupported,
Invalid_Value,
Group_Already_Started,
Runtime_Unavailable);
Result of a loop-thread configuration request.
Enumeration literals
- Configured
New configuration was recorded before startup
- Unchanged
The identical configuration was already recorded
- Unsupported
The host does not implement this placement kind
- Invalid_Value
Value is invalid for Kind or unavailable to process
- Group_Already_Started
Group entered lazy startup before this change
- Runtime_Unavailable
Runtime lifecycle does not permit configuration
Placement_State
type Placement_State is
(Not_Requested, Pending_Startup, Applied, Failed, Unavailable);
Observed application state of a placement request.
Enumeration literals
- Not_Requested
No placement was configured
- Pending_Startup
The request is stored for lazy group startup
- Applied
The group thread applied the request
- Failed
The host call failed; inspect Error_Code
- Unavailable
The requested mechanism is unavailable
Placement_Status
type Placement_Status is record
Kind : Loop_Thread_Placement := No_Placement;
Value : Placement_Value := 0;
State : Placement_State := Not_Requested;
Error_Code : Integer := 0;
end record;
Current loop-thread placement status.
Record fields
- Kind
Requested host placement mechanism
- Value
Requested CPU or advisory tag
- State
Request lifecycle state
- Error_Code
Host error for Failed, otherwise zero
Placement_Supported
function Placement_Supported (Kind : Loop_Thread_Placement) return Boolean
Test whether the host supports Kind without starting a group.
Parameters
- Kind
Placement mechanism to test
Return value
True when the current host supports Kind
Placement_Value
subtype Placement_Value is Natural range 0 .. 2_147_483_647;
Host placement value: zero-based Linux CPU or positive Darwin tag.
Placement_Value_Available
function Placement_Value_Available
(Kind : Loop_Thread_Placement;
Value : Placement_Value) return Boolean
Test a placement value without starting a group. On Linux this may lazily snapshot the process's inherited affinity allowance.
Parameters
- Kind
Placement mechanism
- Value
Candidate CPU or advisory tag
Return value
True when the host can accept the value
Shared_Group_Id
subtype Shared_Group_Id is Group_Id range 0 .. 127;
Shared groups selected by CPU aspects and automatic placement.
Thread_Pin
type Thread_Pin is limited private;
Task-owned scope guard that keeps a lightweight task on its current scheduler thread. Pins nest and each object releases one level. Declare, use, and finalize it in the task that acquires it; do not transfer it. Native tasks accept pins as no-ops because their thread is permanent. @field Active Whether this object owns one pin level @field Owner Runtime identity of the acquiring task