Currently there is no easy way to shutdown agents while making sure all the submitted actions are completed and no new actions are sent.
Here is the naive approach:
(shutdown-agents)
There are two problems with that:
1) It will discard all the actions that have already been submitted, but haven't been started.
2) It won't prohibit from sending further actions to agents (no explicit error will be thrown, just silent ignoring).
Here is the proof:
`
(def my-agent (agent 1))
(defn sleep-and-inc [number]
(Thread/sleep 3000)
(println "action number" number "complete")
(inc number))
(println "sending off 2 times")
(send-off my-agent sleep-and-inc)
(send-off my-agent sleep-and-inc)
(println "sending off complete")
(shutdown-agents)
(println "shutdown requested")
(println "sending off a 3rd time")
(send-off my-agent sleep-and-inc)
(println "sending off complete")
`
Here is the output:
sending off 2 times
sending off complete
shutdown requested
sending off a 3rd time
sending off complete
action number 1 complete
As you can see - the 2nd action got discarded, the 3rd action got ignored.
And btw, the shutdown-agents' docstring is misleading (not clear):
"...Running actions will complete, but no new actions will be accepted"
1) It doesn't say anything about already submitted actions
2) "no new actions will be accepted" sounds like there should be an error, but it's silently ignored.
So, the better docstring should be "...Running actions will complete, waiting actions will be discarded and new actions will be ignored"
A similar naive approach works perfectly well in Java:
`
ExecutorService executor = Executors.newSingleThreadExecutor();
executor.submit(new Runnable() {
@Override
public void run() {
try {
Thread.sleep(3000);
} catch (InterruptedException e) {
throw new RuntimeException(e);
}
System.out.println("Action 1 complete");
}
});
executor.submit(new Runnable() {
@Override
public void run() {
try {
Thread.sleep(3000);
} catch (InterruptedException e) {
throw new RuntimeException(e);
}
System.out.println("Action 2 complete");
}
});
executor.shutdown();
System.out.println("Shutdown requested");
// //will throw RejectedExecutionException
// executor.submit(new Runnable() {
// @Override
// public void run() {
// try {
// Thread.sleep(3000);
// } catch (InterruptedException e) {
// throw new RuntimeException(e);
// }
// System.out.println("Action 3 complete");
// }
// });
`
Output:
Shutdown requested
Action 1 complete
Action 2 complete
By "perfectly well" I mean:
1) It will complete all the waiting tasks (not just running)
2) It will throw an error on a new task after "shutdown" was called.
So, back to Clojure - currently we are only left with this idiom (not trivial!):
(await my-agent)
(shutdown-agents)
It is not a trivial and straightforward idiom, because:
1) You need to keep track of all the agents in the system. Becomes close to impossible if you are dealing with third-party code that uses agents.
2) Still doesn't even throw an exception if you happen to send another action while waiting or shutting down.
Proposal
(inspired by Java):
1) Create a new function called "shutdown-agents-gracefully" which will do 2 additional things:
1.1) Put the agents system to "shutting down" state
1.2) Completes the running actions as well as the waiting actions
2) Modify "send" and "send-off" so that they throw an error in case the agent system is in "shutting down" state.
3) Fix the docstring of "shutdown-agents" (see above)
I'll start developing a patch when this jira ticket is validated.
