Misty Programming Language:Parseq

The parseq module provides tools for working with callbacks and eventual programming. The name combines the prefixes of parallel and sequence.

The parseq module can be passed the @.delay capability.

use parseq(@.delay)

@.delay is only necessary if time limits are used.

Function types

The parseq module works with functions of these types: callbacks, requestors, cancels, and factories.

Callback

Callbacks are a functional pattern used to deliver results from the future. A callback function has a signature of

function callback(value, reason)

If the requestor is successful, it passes the result value to the callback and passes null (or implied null) as the reason.

return callback(valuable_information)

If the requestor fails, it passes the reason to the callback. The value is ignored.

return callback(null, "My dog ate my return value.")

Requestor

A requestor function oversees a unit of work.

function requstor(callback, value)

When the work is complete or has failed, the requestor function calls the callback. The requestor function can optionally return a cancel function.

Cancel

A cancel function can attempt to stop the working of a requestor. It is intended to stop the wasting of resources on work that is no longer needed. It is not an undo. It is not guaranteed to be effective.

function cancel(reason)

Factory

A factory function is a parameterized function that returns a requestor.

Parseq factories

Parseq comes with 5 factory functions that can be used to structure requestor infunctions into useful flows.

Each can take an optional time_limit in seconds. If it is provided, then the operation must finish returns a requestor function. If the time limit is exceeded, then the currently running requestors are cancelled.

Some can take an optional throttle. If supplied, it will constrain the number of requestors that can be running at a time. This can be used to avoid overwhelming fragile systems.

fallback(array, time_limit)

The requestors in the array will be dispatched one at a time until one is successful.

par_all(array_or_record, time_limit, throttle)

The par_all function takes an array of requestor functions or a record of requestor functions, and returns a requestor function that starts them all at once. It ultimately produces an array or a record of all of the results. If any are unsuccessful, or if the time limit is exceeded, then the pending requestors are cancelled and the par_all action fails.

par_any(array_or_record, time_limit, throttle)

The par_any function takes an array of requestor functions or a record of requestor functions, and returns a requestor function that starts them all at once. It ultimately produces an array or a record of all of the successful results. The par_any action succeeds if one or more of the requestors succeed before the time limit.

race(array, time_limit, throttle)

The race function takes an array of requestor functions and returns a requestor function that starts them all at once. If one is successful, then the others are cancelled and the successful value is the result.

sequence(array, time_limit)

The sequence function takes an array of requestor functions runs them one at a time, giving the result of the previous to the next. It is successful if all are successful.