====== @amperka/timer ======

Модуль для работы с объектами-таймерами, которые генерируют событие через равные промежутки времени.

Чтобы что-то происходило регулярно в JavaScript есть встроенная функция ''[[builtins#setinterval|setInterval]]''. Объект-таймер — это обёртка вокруг этой функциональности, которая удобнее в обращении, если тики нужно приостанавливать, запускать заново, смещать фазу или менять период «на лету».

<code javascript>
var myTimer = require('@amperka/timer')
  .create(5); // создаём таймер, тикающий каждые 5 секунд

// Подписываемся на событие-тик
myTimer.on('tick', function() {
  print('Beep');
});

myTimer.run(); // запускаем таймер
</code>

===== Функции модуля =====

func:: create(interval)

Создаёт и возвращает новый объект-таймер с периодом ''interval'' секунд.

По умолчанию таймер остановлен. Используйте ''[[#run|Timer.run]]'' для запуска.

class:: Timer

Класс для работы с таймером. Используйте ''[[#create|create]]'', чтобы создать новый экземпляр.

meth:: Timer.run()

Запускает таймер, заставляя начать генерировать события ''tick''.

Если таймер уже запущен, вызов не имеет эффекта.

Первое срабатывание после запуска произойдёт через время равное периоду таймера.

meth:: Timer.stop()

Останавливает таймер, обнуляет текущую позицию во времени (фазу), //не// приводит к событию ''tick''.

meth:: Timer.reset()

Обнуляет текущую позицию во времени (фазу), //не// приводит к событию ''tick''.

Если таймер не запущен, вызов не имеет эффекта.

meth:: Timer.tick()

Обнуляет текущую позицию во времени (фазу), и моментально приводит к событию ''tick''.

meth:: Timer.isRunning()

Возвращает ''true'', если таймер запущен.

meth:: Timer.interval([val],[units])

Устанавливает или возвращает период срабатывания таймера.

Если параметр ''val'' опущен, возвращает текущий период. Если ''val'' задан — устанавливает.

При установке нового периода если до ближайшего тика оставалось времени меньше, чем новый период, позиция во времени останется без изменений. Если новый период меньше, фаза обнуляется, т.е. следующее срабатывание будет спустя время, соответствующее новому периоду.

Опциональный параметр ''units'' определяет единицы измерения периода:

  * ''"s"'' или не задан — секунды;
  * ''"ms"'' — миллисекунды;
  * ''"m"'' — минуты.

event:: Timer.on('tick', callback)

Происходит при каждом тике таймера. Функция ''callback'' вызывается без параметров.