Timers in Couchbase Functions

We are pleased to announce the support of Timers in the Couchbase 6.0 release. This is an important innovation in Couchbase Functions that enables asynchronous compute in reference to wall-clock events.

Timers are constructs by which developers can specify a routine (business logic) to be triggered at a future time.

Sample Use Cases

• Archive a document before expiry
• Send a notification (SMS or email) to a customer 1-hour post check-in to a hotel
• Filter guests who have not checked in 30 mins before their flight departure
• Near real-time risk assessment for credit card transactions
• Check if a document has changed in a specified time window since it’s last update

Timers Syntax

The way you create a timer is:

createTimer(callback_function, expiry_ts, reference, context_payload)

where:

callback_function: function to be called when the timer is executed

expiry_ts: timestamp at which function is to be executed(Javascript Date Object)

reference: a unique reference id/string

context_payload: additional payload that is to be sent to the call-back function.

Note: The combination of Function-name, callback function and reference has to be unique and, if not, the existing timer is overwritten. Or, in other words, for a given Function, the timers created inside its scope should have a unique combination of callback function and reference.

Sample Code

The following is a sample code that creates a timer that is scheduled to be executed 5 seconds from its creation time.

function OnUpdate(doc,meta) {
   log('document', doc);
   var expiry = new Date(); //get current time
   expiry.setSeconds(expiry.getSeconds() + 5);  //add 5 seconds to it
   var context_payload = {docID : meta.id, random_text : "arbitrary text"};
   createTimer(timerCallback,  expiry, meta.id, context_payload);
}

function timerCallback(context) {
   log('From timerCallback', context);
   dst_bucket[context.docID] = context.random_text;
}

Timer Features

While the construct looks extremely simple and easy to consume, there is quite a lot of heavy lifting that is done by the platform to offer the semantic.

A few notable features include:

• Distributed processing at scale: Automatic sharding of timers across nodes that enables elastic scalability. This also means that timers need not run on the same node that actually created the timer.
• At least one execution of timers despite node failures and cluster rebalances
• Eventual execution of timers in case of a large backlog of events to be processed

Behaviors of Timers

• The bindings that were created for the Function will also be accessible inside the Timers. This keeps the code consistent and readable.
• Timers follow the same timeout semantics as their Parent Functions. So, if a Function has an execution timeout of 60 seconds, each of the timers created from the Function will inherit the same execution timeout value of 60 seconds.
• Timers cannot be debugged using the visual debugger.
• log() messages printed from Timers will be captured in the same application log as the parent Function.
• If the Function is deleted or undeployed, all the associated timers will be also be deleted.
• Timers are not automatically retried if their execution fails due to a runtime or programmatic error. It is recommended that the code be suitably exception handled (i.e. enclose with try-catch block)
• Information about the Timers associated with a Function are stored in the metadata bucket, and hence this bucket should not be deleted or flushed or the keys be updated. It is recommended that the metadata bucket not be used by any other applications.
• As timer information is stored in the metadata bucket, if the use-case mandates and the numbers of timers in the system is high, it is recommended that the memory assigned to the metadata bucket be suitably high as well.

Related Resources

• Download Couchbase Server 6.0
• Learn more about Couchbase Server and Eventing