SUB-EPIC: full port, block, graph, scheduler API

[wirew0rm]

missing API definitions and ideas (from Schulder API Architecture meeting 2023-06-12)

• ports:

  • [x] #210
    • dedicated process_async function (N.B. sync: process_one, process_bulk)
    • rstein will draft a proposal
  • [x] bool optional(): meta information determining whether block has to be connected, can be used by grc and graph setup
    • via Annotation default policy: REQUIRED? or OPTIONAL? solve on UI level? -> Q for Architecture WG -> see: https://github.com/fair-acc/graph-prototype/pull/171
  • [x] auto port_domain()
    • port_domain_t (CPU, GPU, NET, FPGA, …) -- needs demo code -> later -> see: https://github.com/fair-acc/graph-prototype/pull/171
  • [x] auto port_direction()
    • drop BIDIRECTIONAL: unnecessarily complex and only minor benefit over (IN|OUT) pair

• block / node<T>

  • [x] naming: rename all things node to block<T> to comply with gnuradio terminology
  • [x] void reset() mechanics → easy extension to existing settings managment (needs to keep state of initial/default settings)
  • [x] dynamic port definitions -> needs to be addressed (example: adder for 1-10+ input of the same type)
    • follow-up: allows for/enables hier-blocks
  • [x] new -- simplifications/convenience methods: (to note: KISS, clean and lean)
    • [x] std::span availableInputSamples() -- available samples at input ports
      • tbd: updated whenever called (N.B. caller pays the costs for calling)
    • [x] std::span minInputSamples() -- minimum required samples
    • [x] std::span maxInputSamples() -- maximum required samples
    • [x] do we need this for outputs as well? -> not for now
  • [x] BlockingIO-concept -- concept by rstein:
    • scheduler injects atomic counter and thread-pool for each blocking-enabled block
    • same atomic for all blocking blocks (and/or per scheduled CPU core)
    • scheduler waits on atomic counter (N.B. C++20 feature) if there is no more work to be down
    • e.g. spin-loop -> wait based on expoential back-off
    • similar/same strategies as circular buffer 'WaitingStrategy'
    • block/or spawned blocking worker notifies via atomic_counter.notify_all()
    • see: #140
  • [x] #209
    • a) continuous running/looping through graph
    • b) running for a given number of samples and then stop
    • status quo, not ideal:

      enum class work_return_t {
          ERROR                     = -100, /// error occurred in the work function
          INSUFFICIENT_OUTPUT_ITEMS = -3,   /// work requires a larger output buffer to produce output
          INSUFFICIENT_INPUT_ITEMS  = -2,   /// work requires a larger input buffer to produce output
          DONE                      = -1,   /// block has completed processing and the flowgraph should be done -> should become API call ... need ideas
          OK                        = 0,    /// work call was successful and return values in i/o structs are valid
          CALLBACK_INITIATED        = 1,    /// rather than ...
      };
      

  • [x] constraining the amount of 'work' a block is permitted to execute <-> latency optimisation, needs:
    • OK, rstein will make a draft PR + scheduling examples
    • work return indicating how much work has been done (e.g. 1st order number of samples)
    • work input indicating how much work shall be done (same number as above) to limit max execution
    • OK, rstein will make a draft PR + scheduling examples: #105
  • [x] refactoring work() #81
  • MergedGraph<T>
    • [X] naming: merged_block vs MergedGraph
    • [x] misses (sub-)settings() API -> volunteers?
    • [x] misses tag forwarding handling
    • [ ] cannot handle graphs with loops -> Matthias? other volunteers?

• hier-graph -> SubGraph or Graph -> see also #487 & #488

  • [x] needs convenience/helper methods (and Ivan's patch as prerequisite)
  • [x] sub-settings management

• graph:

  • edge<T> interface should be implemented here
    • [x] dynamic runtime definition of buffer sizes
    • [x] dynamic definition of edge priorities for scheduler -> tbd. later
      • either: auto weight() -> float - more graph-theory - vote:
      • xor (vote Ralph): auto priority() -> size_t or dedicated enum: - more OS/scheduling - vote: Alex, Ivan
  • handling of cyclic graphs -- initially handle only one-sample delay case
    • [x] runtime: probably only cycle detection and init-problem (i.e. generating the first zero-padded sample in the buffer where the cycle has been detected)
    • [ ] compile-time merge API: ... needs some work/input from @mattkretz, @ivan-cukic or other volunteers

• scheduler:

  • to note: scheduler is owner of the graph, access/modifications only via scheduler and/or copy of graph
  • [x] define required state-machine of (IDLE, INITIALISING, RUN, PAUSE, ..., SHUTTING_DOWN) -> use this
  • [x] circular graph detection (& handling)
    • run-time graph: resolved by 'init one sample at input'
    • alt: explicit ZOH padding block
    • compile-time graph: see merged_node above
  • [x] optional: performance metrics (<-> use circular_buffer as aggregator and Google perf format): work in progress, see #131
  • [x] long-term: handling of sub-graph and (domain-specific) (sub-)sub-scheduler
    • shall a sub-scheduler behave like a:
      • sub-graph (scheduler behaves like a node), or
      • coordinated/parallel schedule