App lifecycle

[lukego]

This is a proposal for the lifecycle of apps and their callbacks from the engine. Motivation is to neatly support all existing use cases and provide simple and predictable behavior. Especially to resolve #945.

I propose that the callbacks to an app follow this grammar:

new ( link | pull | push | config | tick )* stop

That is: first the start callback, then any number of and link and pull and push and config and tick callbacks, then finally a stop callback.

Callback definitions:

• new(config) => app is called to create the app with its starting configuration. Required.
• link() is called any time the app's input/output links may have been changed (including on startup). Guaranteed to be called before pull and push are called with new links. Optional: no action if absent.
• pull() is called to introduce new packets from external sources into the app network. Optional: no action if absent.
• push() is called to process packets from input links. Optional: no action if absent.
• config(newconfig) is called when the engine wants to change the configuration of the app. Optional: app is recreated if the config is changed and this callback is absent.
• tick() is called every one millisecond. Can be used for pull-like functionality that runs at low frequency. Optional: no action if absent.
• stop(error) is called upon termination. The argument error is nil for graceful termination or otherwise a pcall-style error. Optional: no action if absent.

cc @dpino @alexandergall @eugeneia

[dpino]

I agree with the proposal.

With regard to the start callback I proposed on #905 and which goal was to notify apps when configuration started, so they can do additional stuff (one use case was creating counters by appname), I'd go with @wingo proposed solution in #905 (comment), which was to pass an additional second argument to new with extra information for the app ({ appname=..., shmpath=..}, etc. Example:

function ops.start (name)
   local class = conf.apps[name].class
   local arg = conf.apps[name].arg
   local app = class:new(arg, { appname = name})
   ....
   app.appname = name
   app.output = {}
   app.input = {}

Otherwise, an app should have to wait until link or push to do something which requires the app`s name (create counters by appname in this case).

[eugeneia]

👍 So I guess I will rename configure to link in #945.

create counters by appname in this case

Note that #931 implements private namespaces for per-app counters by default.

[petebristow]

It would be great to have a validate_config or similar. Mixing initialization with config checking is ok in new() for initial start up. On reconfiguration however there isn't any way to communicate that the config was rejected, instead continue running in a the known steady state. YANG when it arrives may enforce that an app must have appropriately named input and output links but it can't enforce that the new pciaddr for Intel82599 is actually a pci device or that the pflang expression passed to packet_filter is valid.

[dpino]

@Eugenia Thanks for the pointer, that covers my use case. As for renaming configure to link, that sounds right to me. Would need to update the docs and the description of configure.