The Collector documentation only states the constraint that reset() must be called at least once before the first start() call.
There is a number of important points that are not addressed and might be useful to formalize, even if they differ from one collector to another:
reentrancy: Whether multiple instances of the collector can be nested successfully. This is not granted and many collectors cannot because of fundamental reasons, but some can (like dmesg if you don't force emptying the buffer).
Whether collection can be interrupted and resumed and what will be the result, i.e. the sequence reset() -> start() -> stop() -> start() -> stop(). It might mean the output is the logical combination of what happened during the first start()/stop() pair and the 2nd one, or it could mean the result of the first start()/stop() is discarded (i.e. implicit reset() on start()).
I think most collectors would simply discard the data during the first start()/stop() pair by virtue of assigning the results to a single attribute in stop() (vs storing it in e.g. a list of results to be combined later). Collectors storing the data straight in their output file would also likely behave this way.
What happens on invalid sequences, such as reset() -> stop() -> stop(): that's the easiest to fix, as we could enforce a state machine with metaprogramming in CollectorBase and raise a consistent exception. We simply need to apply a decorator that checks valid transitions on start(), stop() and reset() using CollectorBase.__init_subclass__. This would avoid having to make a breaking change (e.g. have subclasses define _reset() and let a generic CollectorBase.reset() handle the check)
The Collector documentation only states the constraint that
reset()
must be called at least once before the firststart()
call. There is a number of important points that are not addressed and might be useful to formalize, even if they differ from one collector to another:reset() -> start() -> stop() -> start() -> stop()
. It might mean the output is the logical combination of what happened during the firststart()/stop()
pair and the 2nd one, or it could mean the result of the firststart()/stop()
is discarded (i.e. implicitreset()
onstart()
). I think most collectors would simply discard the data during the firststart()/stop()
pair by virtue of assigning the results to a single attribute instop()
(vs storing it in e.g. a list of results to be combined later). Collectors storing the data straight in their output file would also likely behave this way.reset() -> stop() -> stop()
: that's the easiest to fix, as we could enforce a state machine with metaprogramming inCollectorBase
and raise a consistent exception. We simply need to apply a decorator that checks valid transitions onstart()
,stop()
andreset()
usingCollectorBase.__init_subclass__
. This would avoid having to make a breaking change (e.g. have subclasses define_reset()
and let a genericCollectorBase.reset()
handle the check)