github.com/anth0d/nomad@v0.0.0-20221214183521-ae3a0a2cad06/client/allocrunner/tasklifecycle/doc.go (about)

     1  /*
     2  Package tasklifecycle manages the execution order of tasks based on their
     3  lifecycle configuration. Its main structs are the Coordinator and the Gate.
     4  
     5  The Coordinator is used by an allocRunner to signal if a taskRunner is allowed
     6  to start or not. It does so using a set of Gates, each for a given task
     7  lifecycle configuration.
     8  
     9  The Gate provides a channel that can be used to block its listener on demand.
    10  This is done by calling the Open() and Close() methods in the Gate which will
    11  cause activate or deactivate a producer at the other end of the channel.
    12  
    13  The allocRunner feeds task state updates to the Coordinator that then uses this
    14  information to determine which Gates it should open or close. Each Gate is
    15  connected to a taskRunner with a matching lifecycle configuration.
    16  
    17  In the diagrams below, a solid line from a Gate indicates that it's open
    18  (active), while a dashed line indicates that it's closed (inactive). A
    19  taskRunner connected to an open Gate is allowed to run, while one that is
    20  connected to a closed Gate is blocked.
    21  
    22  The Open/Close control line represents the Coordinator calling the Open() and
    23  Close() methods of the Gates.
    24  
    25  In this state, the Coordinator is allowing prestart tasks to run, while
    26  blocking the main tasks.
    27  
    28  	         ┌────────┐
    29  	         │ ALLOC  │
    30  	         │ RUNNER │
    31  	         └───┬────┘
    32  	             │
    33  	         Task state
    34  	             │
    35  	┌────────────▼────────────┐
    36  	│Current state:           │
    37  	│Prestart                 │         ┌─────────────┐
    38  	│                         │         │ TASK RUNNER │
    39  	│     ┌───────────────────┼─────────┤ (Prestart)  │
    40  	│     │                   │         └─────────────┘
    41  	│     │                   │
    42  	│     │                   │         ┌─────────────┐
    43  	│     │ COORDINATOR       │         │ TASK RUNNER │
    44  	│     │             ┌─ ─ ─┼─ ─ ─ ─┬╶┤   (Main)    │
    45  	│     │             ╷     │       ╷ └─────────────┘
    46  	│     │             ╷     │       ╷
    47  	│     │             ╷     │       ╷ ┌─────────────┐
    48  	│   Prestart       Main   │       ╷ │ TASK RUNNER │
    49  	└─────┬─┬───────────┬─┬───┘       └╶┤   (Main)    │
    50  	      │ │Open/      ╷ │Open/        └─────────────┘
    51  	      │ │Close      ╷ │Close
    52  	   ┌──┴─▼─┐      ┌──┴─▼─┐
    53  	   │ GATE │      │ GATE │
    54  	   └──────┘      └──────┘
    55  
    56  When the prestart task completes, the allocRunner will send a new batch of task
    57  states to the Coordinator that will cause it to transition to a state where it
    58  will close the Gate for prestart tasks, blocking their execution, and will open
    59  the Gate for main tasks, allowing them to start.
    60  
    61  	         ┌────────┐
    62  	         │ ALLOC  │
    63  	         │ RUNNER │
    64  	         └───┬────┘
    65  	             │
    66  	         Task state
    67  	             │
    68  	┌────────────▼────────────┐
    69  	│Current state:           │
    70  	│Main                     │         ┌─────────────┐
    71  	│                         │         │ TASK RUNNER │
    72  	│     ┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┼─ ─ ─ ─ ─┤ (Prestart)  │
    73  	│     ╷                   │         └─────────────┘
    74  	│     ╷                   │
    75  	│     ╷                   │         ┌─────────────┐
    76  	│     ╷ COORDINATOR       │         │ TASK RUNNER │
    77  	│     ╷             ┌─────┼───────┬─┤   (Main)    │
    78  	│     ╷             │     │       │ └─────────────┘
    79  	│     ╷             │     │       │
    80  	│     ╷             │     │       │ ┌─────────────┐
    81  	│   Prestart       Main   │       │ │ TASK RUNNER │
    82  	└─────┼─┬───────────┬─┬───┘       └─┤   (Main)    │
    83  	      ╷ │Open/      │ │Open/        └─────────────┘
    84  	      ╷ │Close      │ │Close
    85  	   ┌──┴─▼─┐      ┌──┴─▼─┐
    86  	   │ GATE │      │ GATE │
    87  	   └──────┘      └──────┘
    88  
    89  Diagram source:
    90  https://asciiflow.com/#/share/eJyrVspLzE1VssorzcnRUcpJrEwtUrJSqo5RqohRsjI0MDTViVGqBDKNLA2ArJLUihIgJ0ZJAQYeTdmDB8XE5CGrVHD08fF3BjPRZYJC%2Ffxcg7DIEGk6VDWyUEhicbZCcUliSSp2hfgNR6BpxCmDmelcWlSUmlcCsdkKm62%2BiZmo7kEOCOK8jtVmrGZiMVchxDHYGzXEYSpIspVUpKAREOQaHOIYFKKpgGkvjcIDp8kk2t7zaEoDcWgCmsnO%2Fv5BLp5%2BjiH%2BQVhNbkKLjyY8LtNFAyDdCgoavo6efppQ0%2FDorkETrQGypxDtrxmkmEyiK8iJ24CiVGAeKyqBGgPNVWjmYk%2FrVE7X8LhBiwtEcQRSBcT%2B%2Bs4KyK5D4pOewlFMRglfuDy6vmkoLoaL1yDLwXUquDuGuCogq4aLYDd9CnbT0V2uVKtUCwCqNQgp)
    91  */
    92  package tasklifecycle