Tuesday, October 30, 2012
In the last post, we took a look at basic usage of Clojure's agent function. In this post, we'll dive a little bit deeper
We glossed over the options that you can define when creating an agent; one of them is the validator which one can use to check before the agent is updated with the passed value.
If we want to make sure that our read-agent always gets a string value, this is all we have to do:
Similarly, any function that takes a single value as a parameter can be used here. As you can see, we had to change our default value for the agent from nil to "" since there is now a string validator. If we hadn't, any time we tried to use that agent, we'd get java.lang.IllegalStateException.
When Things Go Wrong
Another option you can set when defining an agent is the error handler. This will be used in the event of an error, including if a value fails to be validated by your validator function. Here's an example:
With both of these options, you don't have to set them when the agent is defined; you can do it later with a function call, if you so desire (or if needs demand it):
So, we've got an error handler but no event handler? Yup. However, you can actually get callback-like behavior using watches. Check this out:
Now, any time our agent's state changes, the function passed to the watch will fire. As described in the docs, the parameters are: the agent, a key of your devising (must be unique per agent), and the handler that you want to have fired upon state change. The handler takes as parameters: the key you defined, the agent, the agent's old value, and the agent's new value.
All Together Now
With all our example code in place, we can now exercise the whole thing at once. Here's the whole thing:
To simply demonstrate the async nature and the callbacks in action, let's run the following:
Eventually, our callback will render output very much like the following:
Do note, however, that if we called a series of send-offs with different times (using the same agent and watch), we wouldn't see the ones with shorter times come back first. We'd see the callback output in the same order we called send-off. This is because the watch function is called synchronously on the agent's thread before any pending send-offs (or sends) are called. In future posts, I'll cover ways around this (constructing agents on the fly as well as exploring alternative solutions with external libraries).
Regardless, with these primitives, there are all sorts of things one can do. For instance...
To close, check out this neat little bit of code that sends 1,000,000 messages in a ring. This code creates a chain of agents, and then actions are relayed through it (taken from the agents doc page):
Kicking this puppy off, our million messages finish in about 1 second :-)