Darklang's built-in queues allow programs to be run in the background.
emit to add events into a named queue, which will be executed
asynchronously by a handler of the same name.
Events are stored in a system-wide queue and run on separate worker machines, whose capacity is shared with other users. We automatically scale these workers up, and you should expect your events to be run promptly.
Cron jobs are also run using the same infrastructure.
Running an event
When a Worker handler runs, the event that was
emited will be available as an
event parameter available in the Worker.
When viewing a handler, you can see the number of items in the queue. When an event is completed, a trace will be stored where you can view the execution.
Events are considered successful if they run to completion, and will not be
retried based on the result of the worker's expression, even if that value is a
false, or any other "negative value".
If you wish to retry when there is an error of some sort, you should handle this
explicitly in your code, perhaps
emiting a new event.
Events are run as quickly as we can, you cannot be assured that an event will wait for a previous event to complete before running - in fact, it probably will not.
Events are also not guaranteed to process in the order they are
Handlers can be paused. When handlers are paused, they will continue to allow
events to be
emited, but they will not run the event. When handlers are
unpaused, all the events will start to run as soon as possible.
Darklang admins may
block handlers that are causing operational issues. Queues
that are causing a operation issue (perhaps even just setting off an internal
alarm) may be blocked while we investigate. When (and if) we rectify the issue,
we may unblock the problematic queue, which acts just like unpausing.
Events in the queue will be retried if something goes wrong in the infrastructure. We will attempt to run an event until it succeeds, trying at most 5 times for each event. This only happens with infrastructure issues, which you do not have visibility into, so you cannot predict how many retries a event will get.
The most common situation is if an event runs longer than 25 seconds, and runs while the Darklang infrastructure is being redeployed. In this case, some of the code may be executed more than once - however much got completed on the first try, and then however much got completed in the retry. While unlikely, events like this could be retried more than once. The best way to avoid this is to have your events complete more quickly.
Events which have no handler or where the canvas has been deleted will not be retried.
You can read the technical detail and implementation of our queues.