====== kmj-intervals ======

The kmj-intervals package provides access to the ability to defer execution of a function and/or have it be executed repeatedly at a given interval.

The runtime provides this library through the [[https://www.lua.org/manual/5.4/manual.html#luaL_newlib|luaL_newlib]] auxiliary library function, so all fields can be assumed to be functions.

===== create =====

The create field contains a function that allows for the registration of an interval. No arguments are provided to the function and nothing is done with any values it may return.

Like the equivalent ''setInterval'' and ''setTimeout'' functions in Javascript, the first execution of the function will be after the specified delay. If your intention is for the function to have an initial invocation, then you must do so yourself, like the following example:

  intervals.create(poll, 60)
  poll()

==== Syntax ====

  create(action: function, number: delay, number: times = -1): (interval: number)

==== Arguments ====

  - The first argument should contain the function that is to be run at an interval or be deferred.
  - The second argument contains the delay **in seconds** between executions.
  - The third argument contains the amount of times the interval should be run, if **''-1'' or any other value less than ''0''**, the interval will run indefinitely, if **''0''**, the interval creation will essentially be a no-op, **any value greater than ''0''** will have the value decrease with ''1'' every time it is run, until the value reaches ''0'' at which point it is destroyed.

==== Returns ====

  - The first return value contains a unique identifier representing the interval registration. It can be used to (prematurely) destroy it to prevent it from running further.

===== destroy =====

The destroy field contains a function that can be used to prevent a registered interval from running (again).

==== Syntax ====

  destroy(interval: number): ()

==== Arguments ====

  - The first argument should contain the unique identifier of an interval returned at creation.

==== Returns ====

//This function does not return anything.//