Chronicle-Threads

Chronicle-Threads copied to clipboard

The "threads" library is in need of documentation and code cleanups:

• What is the life-cycle of an EventHandler/EventLoop?
• When are methods invoked?
• By which threads are methods invoked?
• When does an EventHandled become eligible for scheduling?
• Is the loopFinished() guaranteed to be invoked exactly one time?
• What happens if loopFinished() throws an Exception?
• What is the purpose of EventHandler::eventLoop?
• When and why is a potential Close method invoked?
• Is the Close guaranteed to be invoked exactly one time?
• What happens if close throws an Exception?
• Can an EventHandler be added a plurality of times to an EventLoop?
• Can an EventHandler be added a plurality of times simultaneously to an EventLoop?
• Can an EventHandler be added to a plurality of EventLoops?
• Can EventLoop::addHandler block the calling thread and if so, for how long? (presently, indefinitely under some conditions)
• When can an EventHandler be added to/removed from an EventLoop?
• What is the individual order (if any) of EventHandlers within an EventLoop?
• Are there any guarantees on fairness amongst EventHandlers?
• Is the order of invocation on retained EventHandlers time-invariant ? (it is not today)
• Why is the base interface named VanillaEventHandler when it is not an implementing class?
• What is the contract when observing an EventHandler/EventLoop using another thread?

Also, test coverage should be improved, especially as most other modules rely heavily on the threads module.

I can document some of this - will do tomorrow.

Have added some javadoc although we need some better doco in the README

@minborg lets hold off making any changes to threads for the moment as we have some code in chronicle fix that relies on it working in the way it does currently.

@RobAustin I believe this can be closed as javadoc has been written and a lot more tests exist now to validate all invariants

Closing this as Jerry's comment indicates it has been completed.