1    Introduction

hara.function.procedure provides a wrapper for controlling the execution of concurrent operations. Many features are added in order to support use in the real world. These include restarts, interrupts, timeouts, caching, synchronous/asynchronous dispatch, timing and other issues associated with concurrent systems.

The library provides rich information about the execution of a particular running instance:

• the function that originated the process instance
• the thread or future on which the instance is executing
• the result (maybe cached) of the execution if returned
• the time of execution
• the id of the process (used for identification)
• other running instances of the process

1.1    Installation

Add to project.clj dependencies:

[hara/function.procedure "3.0.2"]

All functions are in the hara.function.procedure namespace.

 (use (quote hara.function.procedure))

2    API

3    Features

3.1    Basics

There are many uses for a function that stores information about it's execution, as well as having it's execution properties be customised through input arguments. This will be demonstrated by creating a very simple function that waits for a second before outputting a result. As can be seen, there is an additional map before the argument vector and it's use will be shown later.

We can call hello and see that it yields a future-like reference for the execution of the function. This will be called an instance of execution.

The result of the function is shown after one second when dereferenced.

3.2    Mode

We now change the procedure slightly by setting the mode to :sync, by default the mode is :async

Notice that the call to hello does not return immediately but pauses for one second before returning the execution instance. Instead of running asynchronously like before, the call is synchronous. Notice that :runtime has an end time and there the value for :result has changed from :waiting to a map having :type and :data keys.

When it is dereferenced, there is no difference between the dereference second and the first hellos

3.3    Control of Execution

Lets add another option to our procedure, this time :arglist

We should be familiar with the call to hello because it behaves the same to the previous definitions when called directly:

However, we can play with what mode we wish the function to run by running hello with an additional argument:

When it is dereferenced, there should be no difference of behavior to the previous definitions.

The :arglist can be seen as an outer wrapper on top of the original function. The arglist count should always be equal or more than the function's argument count. In this way, the execution of the function can be controlled by the caller using only data. This is extremely useful as will be seen next:

3.4    Instance

There are special keywords that we can put in the :arglist vector in order to adjust the behavior of execution. The most general is :instance. With :instance, we can overwrite any execution property. This is shown in an example below:

We can see what the instance variable passed to the function actually contains:

In fact, this structure is exactly what we get when we call hello without dereferencing:

3.5    Runtime and Registry

We can look at the function's execution through it's :runtime and :registry keys. We can reuse the previous definition of hello to create two long running functions:

Now that we have the instances of execution, we can view when it has been started:

As well as access all running instances through a global registry:

We can stop the execution of instance a:

A check will reveal that instance b is still running

instance-b is accessible from instance-a:

As well as to be killed from from instance-a:

This is very useful for coordinating strategies between execution instances.

3.6    Identity and Caching

In the previous section, there were concepts like :id and :name being introduced. These properties give context to the type of function being executed as well as to identify duplicates and wasted execution. To be able to uniquely identify an instance of execution as being the same as another means that additional operations such as caching, timeouts and interrupts can be used for control of execution.

Let's look at a particular use case where results can be cached. The power function has been written using defprocedure to include caching.

More about the parameters will be explained later but first, let's try this out. We will calculate 20! and see the caching kick in after the second try:

Sometimes, we actually wish to ignore the cache and have it recalculate. This can be done through arguments instead of any special forms

We can look at the cached values directly from the instance:

In concurrent applications, where multiple processes may be doing the same calculation, this type of mechanism will be able to save quite a few clock cycles when used in the right way.

3.7    Intermission

Let's switch gears a little bit and talk philosophy. In working with the standard concurrent execution contructs like futures and promises, it was found that they lacked the self-awareness to coordinate with each other. The reason behind this is very simple: there is dissociation between what should be three concepts critical to concurrent execution: the function (governed by its definition), the execution (governed by time) and the result (governed by input).

3.7.1    Synchronous Execution

Execution is not an issue in a synchronous world; it occurs with the ticking of the system clock and there are no other processes that are able to affect the world, we can establish a link between the past and the future because there is no present as such in terms of what is happening right now. It just doesn't exist, or rather we don't need to account for it in order to build our programs. In the synchronous world, there is no difference between a function and a lookup table of inputs and outputs

3.7.2    Concurrent Execution

In the concurrent world things happen very differently; or rather, things are required to be accounted very differently in order for a program to succeed. Time the conquerer is the master behind all calculation. To neglect time is a idealistic and will ultimately result in failure.

3.7.3    Coordination of Concurrent Execution

An example of how this could be useful can be shown below.

Computation C is estimated to take 10 hours to complete and both process A and process B both require the same result. Now, process A has started computation for 9 and a half hours but has not finished and process B is starting. In this case, instead of waiting another 10 hours for computation, if process B is aware that process A is already doing the computation, all it needs to do is to wait on the result of A instead of starting from scratch.

Instead of taking 10 hours, process B will just take 0.5 hours.

3.8    Overwrite

Caching is a part of the bigger problem of how calculation can be shared between one or more concurrent processes. So when working with caching, we have to think about coordination and how processes should be able to work together. Lets try this out with a function that returns a random integer between 0 and 1000.

Lets give this a go by making two calls and watching the cache kick in:

This is may or may not be good depending on the problem. Imagine something like multiple concurrent processes hitting a database to retrieve the same value. Sometimes, we want to make a call without affecting everyone else; other times, we would wish to make a call and then update it globally for all processes. A combination of :cached and :overwrite allows this to happen.

In the first case, we see that :overwrite true will update the cache with a new value:

In the second case, we see that :cached false will return the value whilst skipping the cache altogether

3.9    Interrupt

Another important characteristic is that sometimes, a process is taking too long and we need to restart it. We construct a function showing 50% chance of failure.

The function behavior can be activated by calling it a few times. As the probabily of failure is quite high, We find that there is no output for Function Finished.

Our function is set so that another call of the same type will just wait, subsequent calls will block for the calculation:

By default, a called procedure will block and wait on another of the same type to finish before returning the result. However, if it is required to kill a procedure that is taking too long to finish, setting :interrupt true will interrupt the current execution and proceed again from the beginning:

This is used for mitigating coordination problems when one process is waiting on the other without reason.

3.10    Time

We can access information about the instant's start and end time through the :runtime key. The :timestamp key is used for coordination between processes that may have started at slightly different times due to the randomness of the thread pool. We see an example below:

A call to current returns information about the operation:

By default, the value of :timestamp is same as :started. However, we can also pass in the exact :timestamp we want the function to have as it's argument.

4    Retries

In the real world, there is always going to be failure and having the ability to deal with failure is key to system robustness. Retries are a very important feature for any concurrent process as it allows for strategies to be implemented on failure.

When a function throws an exception, we wish to then be able to adjust and calmly start again with either the same call or another strategy for mitigation. Although this can be done using try/catch blocks, hara.function.procedure offers an elegant alternative.

4.1    Simple

We can construct the most basic retry

Lets run the function and see what happens:

Notice that the function starts, errors and then retries 3 times, pausing 1000ms before each retry. Once it reaches the limit of 3, the function gives up and throws the error.

4.2    Wait

An important variable to control is the wait time. We construct the next example to explain this feature:

Instead of using a fixed value for the wait time, it is controllable by passing a function taking two parameters: state (which is used to hold data about the current status of the retries) and count (the number of retries attempted). The output of this function is shown below:

4.3    Arguments

The difference between hara.function.procedure and other libraries for concurrent constructs lie in the fact that the modes of operation such as caching, timing, threads and other runtime decisions can be passed to the function itself. This also applies to retry strategies as well. can be passed in as arguments to affect how a function is evaluated. We see an example of a procedure:

When it is called directly, the output is predictable:

When it is called with retry options, there is a very different output:

The advantage of this approach is significant. Most of the time, the modes of execution are hard-coded and so cannot be changed. With parameterised control of execution, how a function is run is now totally in the hands of the caller and so allows much more freedom and flexible for how systems can be defined.

4.4    Handlers

The retry handler mechanism is compatible with hara.event and offers the same semanitics for querying on exception data. Notice that multiple handlers can be set up for the procedure.

We can see the results of the output:

Lets talk a little about state. In many failure scenarios, there are particular strategies that one needs to apply in order to mitigate a particular situation. :apply is a way to manipulate the state based upon the previous state and the exception that occurred. Using a combination of :apply and :wait will allow most retry strategies to be expressed.

Some more sample :handlers can be seen below. The parameters outside of the :handlers vector are default values.