Heartbeats
A simple module to very efficiently manage time-based objects and events.
Use this library for comparing large numbers of relativistic time lapses efficiently and for synchronizing the execution of events based on these time lapses. In effect:
- Execute functions on specific Heartbeat intervals
- Compare the time properties of multiple objects (Pulses) to a global time measure (Heart) operating on a specific time resolution (Heartrate)
This library uses a much more efficient (lower resolution) method of testing system level event times as relativistic time differentials (vs. universal time differentials). Think larger chunked time measures (interval counts) instead of actual milliseconds. It's also great at managing the execution of events that require precise in-system synchronization.
Basic Usage
Install
npm install heartbeats
Add to your project
var heartbeats = ;
Create a New Heart
A Heart
is the main object you use to measure time. It has a core heartrate, and beats at a specified time interval (in milliseconds).
// a heart that beats every 1 second.var heart = heartbeats;
The running essence of the Heart
is its own internal heartbeat count. How many times has it beat? We call this the Heart's age.
var age = heartage;
Heart Events
Hearts manage Events, and execute blocks on specific heart beats, either continually (like setInterval
) or just once (like setTimeout
).
This is much more efficient and much more reliable than using multiple setInterval
methods, as they usually get unsynchronized, and introduce memory issues.
// Alternative to setIntervalheart; heart; heart; // Alternative to setTimeoutheart;
Heart Pulses
A Pulse
is an object used to measure how synchronized part of your system is to a central Heart
. This is super useful as it allows you to very efficiently measure if things are lagging, or working as they should with respect to that heartbeat
.
var pulseA = heart;var pulseB = heart;
Now, instead of storing an event's time as Date().now()
or Date().getTime()
and comparing those values to some other time, you pulse.beat()
to synchronize the Pulse's time with its Heart.
pulseA;pulseB;
So, if we want to know how far off an object is from the Heart, we can use the Pulse's missedBeats
property. For example:
console; // 0console; // 0 ;
Kill That Heart
Like any ongoing interval, you should kill the Heart once you no longer need it, otherwise it's likely your program will not exit until it has been properly killed.
heart;
About Efficiency
Why is this library faster than more conventional methods? Basically, instead of using Date().now()
or new Date().getTime()
which are relatively very slow operations that give you very precise, universal values for the present time, we use the present moment of a heartbeat to give your events a time relative to that particular heart. This simple change results in extremely fast and efficient time difference calculations because it operates at a very low resolution compared to methods using the Date object, and compares basic integers vs comparing dates. View the source to see details.
Test Performance
If you're curious, I've included a performance test using benchmark.js
which compares a more traditional way of testing times.
# switch to the heartbeats module directory cd node_modules/heartbeats # install dev dependencies for the heartbeats module npm install # run benchmark test npm run benchmark
Have a look at the benchmark.js
file in the tests directory to see how the benchmark is done.
API
The API is fairly straightforward, though it's good to be aware of nuances in its use.
The Heart
heartbeats.createHeart(heartrate, name);
Creates and returns a new Heart
object.
If you provide a name, the heart is registered in the module's list of hearts (see heartbeats.heart()). This is useful if you want to access heartbeats from different modules.
// a new heart that beats every 2 seconds named 'heartA'var heart = heartbeats;
If you don't provide a name, the heart will be returned but will not be added to the heartbeats.hearts
object.
var heart = heartbeats;console; // heart_kajg8i27tjhv
heartbeats.hearts
An object with all hearts that have been instantiated with a name.
heartbeats.heart(name)
Returns a Heart
object with a name from the managed list of hearts.
// gets a heart named 'heartA'var heart = heartbeats;
heartbeats.killHeart(name)
Removes the Heart
from the internal managed list and clears the heartbeat interval. This only works if the heart was created with a name
.
// destroys the 'heartA' heart(beat)heartbeats;
heart.kill()
Clears the heartbeat interval and removes the Heart from the internal managed list if it exists there.
heartbeats;
heart.setHeartrate(heartrate)
Updates the heartrate period of the Heart
and returns the Heart
object for chaining.
heartbeats;
heart.age
Gets the current number of beats that the heart has incremented in its lifetime.
heartbeatsage;
The Pulse
heart.createPulse(name);
Returns a new Pulse object associated with the heart.
If you provide a name, the Pulse is added to the Heart's internal managed list of Pulses (ie. heart.pulses
). This is useful if
// creates a new pulse from the 'heartA' heart(beat)var pulse = heartbeats;
If you don't provide a name, the pulse will be returned without being added to the Heart's managed list of Pulses.
var pulseA = heartbeats;
heart.pulses
An object with all pulses belonging to the heart, that have been instantiated with a name.
heart.pulse(name);
Returns the Pulse object from the heart's managed list of pulses.
var pulseA = heartbeats;
heart.killPulse(name);
Kills the Pulse and removes it from the heart's managed list of Pulses.
var pulse = heartbeats;
pulse.kill()
Kills the pulse and removes it from its heart's managed list (if it exists there).
// clears the pulse from memorypulse;
pulse.beat()
This synchronizes the pulse with its Heart. This is the secret sauce. Instead of using Date().now()
or Date().getTime()
to register an event time we match the time of the pulse with the heart.
Returns the Pulse
object to chain if needed.
// synchronizes the pulse to its heartpulse;
pulse.missedBeats
The number of heartbeats that have passed since the pulse was last synchronized with pulse.beat()
.
// gets the number of beats the pulse is off from its heartvar beatoffset = pulsemissedBeats;
pulse.lag;
Returns an approximate number of milliseconds the pulse is lagging behind the main heartbeat. Basically this is pulse.missedBeats*heart.heartrate
.
// gets an approximate number of milliseconds the pulse is delayed from the heartvar delay = pulselag;
Beat Events
heartbeats
makes it easy for you to synchronize event execution without the need for multiple setInterval
or setTimeout
initializers. It ensures that actions are synchronized with respect to the heart's beat and uses the heartbeat as the measure for action, and won't get unsynchronized as is what happens when multiple setInterval
or setTimeout
methods are used.
heart.createEvent(beatInterval, options, function)
This method is slightly different from the other creation methods (ie. createHeart
and createPulse
). Giving the object a name is done by passing a value to the options object.
This method will add a reoccuring event to the heart. Every nth
beat specified by beatInterval
will execute the supplied function. This method counts from the time you add the event. It's kind of like setInterval
.
Options
name
: Give the Event a custom name, so you can reference it, kill it, or modify it using heart.event(name)
countTo
: default is 0
(infinite). Iterate the event a specified number of times (use 0
for infinite). If set to a finite number, the event will be killed and cleared from memory once executed the last time.
Callback Function
The callback function is called with count
and last
as arguments.
The following example creates a new event called checkA
, on an existing heart named heartA
that executes every 5th beat, repeats forever. The last
argument passed to the callback will always be false
.
var event = heartbeats;
The following example creates an anonymous event on the heart named heartA
that excutes every 4th beats but stops once it has been executed 3 times.
heartbeats;
heart.event(name)
Returns the Event
with the specified name from the heart.
var event = heartbeatsevent'checkA';
heart.killEvent(name)
This will instantly kill the event specified by the name.
heartbeats;
heart.killAllEvents()
This will clear all beat events from the heart.
heartbeats;
event.kill()
This will instantly kill the event specified by the name.
heartbeatsevent'checkA';
License
The MIT License (MIT)
Copyright (c) 2016 Arjun Mehta