Add documentation on task execution stages

[oraNod]

Follows on from #1282

Purpose of this issue is to capture precedence of features like timeout, async, and retries. The docs should explain the scope and purpose of these features as well as how they interact with the execution engine.

[oraNod]

Here are bcoca's notes to use as a starting point:

# format:
#	keyword: *dependencies <priority>
#	_<alias>: *dependencies

# 'keyword' maps to an engine keyword on the task playbook object, higher priority means it needs to be templated sooner.

# '*dependencies' declares what other keywords or resources (like play or host vars) are required to be templated beforehand as they are used as input
#	for the current keyword,  they are expressed just with direct dependencies, but on execution translate to the full chain, i.e 'action' depends on '_l'
#	(aka 'loop'), then 'loop' depends on 'host vars' and 'collections' and so on.

# '_' aliases, cause im lazy and don't want to copy lists all over

# '!static' means this is not a templatable keyword

# #C@ <event> are callback entries

# playbook_executor handles play/playbook callbacks, all named playbook but only 1/2 are:
# v2_playbook_on_vars_prompt, v2_playbook_on_play_start, v2_playbook_on_no_hosts_matched, v2_playbook_on_stats v2_playbook_on_no_hosts_remaining

# note: imports have their own path and should have happened by now and meta tasks are processed pre fork and have their own logic depending on which one it is.

#####################
##### pre execution
#####################

# these are 'task' vars which includes parent resolution (block/role/play) but does not template the var values themselves
# variables are still only templated on consumption
vars: 100
collections: !static 99
listen: !static 99

_templ: *vars, *collections

# required early for iterator task/host selection
throttle: *_templ 95

# iterator must handle --start-at-task and tag evaluation to decide on task being selected for execution
name: *_templ 90
tags: *_templ 90

# task/handler is ready to run
# C@: v2_playbook_on_task_start

# host task/handler is queued, yes kind of redundant with previous,
# C@: v2_runner_on_start

# here we star reading from task/host queue
# controls host selection by iterator (run on first), in post it controls setting facts/register for all
run_once: *_templ 80

# process includes, create blocks for new tasks, start again at pre execution for each (except include_vars, which is normal task)
#C@: v2_playbook_on_include

#### from here main process goes continues loop to process results, queue tasks/pull from queue (pre fork)
### FORK
#### below we are forked and in worker (post fork)

# not really needed here, but we process early, both are only really used inside loop, but we don't allow 'per loop item' setting
async: *_templ 80
poll: *_templ 80

_templ2 : *host vars, *collections


loop: *_templ2 70
loop_control: *_templ2 70
with_: *_templ2 70

_l: *loop, *loop_control

#######################
#######  loop prep
#######################

# both these get special outside loop evaluation and treatment, on outside loop template error both default to 'true' and then can evaluate again per item
when: *_l 60
no_log: *_l 50

# until/retry handling
retry: *_l 40
delay: *_l 40

# task timeout, not to be confused with connection timeout
timeout: *_l 40

check_mode: *_l 35
delegate_to: *_l 35
debugger: *_l 35
diff: *_l 35
environment: *_l 35
module_defaults: *_l 35

#######################
#######  task (item) executes
#######################

# actual action plugin/module to execute, these cannot coexists as local_action is basically an alias of 'action + delegate_to: localhost'
action: *_l 30
local_action: *_l 30
# TODO:  need to check if it local_action bomb with delegate_to

# become plugin settings
become: *_l 25
become_exe: *_l 25
become_flags: *_l 25
become_user: *_l 25
become_method: *_l 25

# connection plugin selection/settings
connection: *_l 25
remote_user: *_l 25
port: *_l 25

_conninfo: become, become_exe, become_flags, become_user, become_method, connection, remote_user, port

# these are 'module options', processed both as the explicit task keyword or if specified directly set to the action/module
args: *action, *conninfo 20

# This section is only relevant if there is a loop, otherwise it is skipped and processing is moved to 'task final'
# all items are x2 processed this way
# TODO: x2 check _when/ignore_ ordering, might be diff inside loop to final task handling



########################
####### task item result
#######################
# here (per loop item) it shows previous item in loop and no 'results' key
# if using as input in the following 'still in loop' requires |default for first loop item as there is no 'previous result'
register: !static *_item_result

delegate_facts: *_l, *register 15
failed_when: *_l, *register 15
changed_when: *_l, *register 15

any_errors_fatal: *register, *failed_when 10
ignore_errors: *register, *failed_when 10
ignore_unreachable: * register, *failed_when 10

notify: *register, *changed_when 10

#C@: v2_playbook_on_notify

#C@ v2_runner_item_on_{ok|failed|skipped}
#C@ v2_on_file_diff

# loop has ended or been skipped, now we summarize per task
########################
####### task final
#######################

####  worker above becomes free
### POST FORK
#### below we are back in main process in 'processing_results' thread

# if loop, has 'results' list with each item return in order, summarized states accessible as normal
register: !static *_results

delegate_facts: *_l, *register 5
failed_when: *_l, *register 5
changed_when: *_l, *register 5

any_errors_fatal: *register, *failed_when 0
ignore_errors: *register, *failed_when 0
ignore_unreachable: * register, *failed_when 0

notify: *register, *changed_when 0

#C@: v2_playbook_on_notify

# async polling happens here if needed as it's own task
#C@ v2_runner_on_poll
#C@ v2_runner_on_async_{ok|failed}

# this is where until loop gets triggered and can rerun task from start, start again
until: *register, *failed_when, *changed_when 0

#C@ v2_runner_on_retry
#C@: v2_runner_on_failed v2_runner_on_unreachable v2_runner_on_skipped
#C@: v2_on_file_diff