docs: improve docs for timers interface

readline-upstream
sammyette 2022-12-28 19:32:52 -04:00
parent 0f33f72de7
commit 61f6337f5f
Signed by: sammyette
GPG Key ID: 904FC49417B44DCD
2 changed files with 25 additions and 41 deletions

View File

@ -1,38 +1 @@
If you ever want to run a piece of code on a timed interval, or want to wait This has been moved to the `hilbish.timers` API doc (accessible by `doc api hilbish.timers`)
a few seconds, you don't have to rely on timing tricks, as Hilbish has a
timer API to set intervals and timeouts.
These are the simple functions `hilbish.interval` and `hilbish.timeout` (doc
accessible with `doc hilbish`). But if you want slightly more control over
them, there is the `hilbish.timers` interface. It allows you to get
a timer via ID.
# Timer Interface
## Functions
- `get(id)` -> timer: get a timer via its id
- `create(type, ms, callback)` -> timer: creates a timer, adding it to the timer pool.
`type` is the type of timer it will be. 0 is an interval, 1 is a timeout.
`ms` is the time it will run for in seconds. callback is the function called
when the timer is triggered.
# Timer Object
All those previously mentioned functions return a `timer` object, to which
you can stop and start a timer again.
An example of usage:
local t = hilbish.timers.create(1, 5000, function()
print 'hello!'
end)
t:stop()
print(t.running, t.duration, t.type)
t:start()
## Properties
- `duration`: amount of time the timer runs for in milliseconds
- `running`: whether the timer is running or not
- `type`: the type of timer (0 is interval, 1 is timeout)
## Functions
- `stop()`: stops the timer. returns an error if it's already stopped
- `start()`: starts the timer. returns an error if it's already started

View File

@ -119,9 +119,30 @@ func (th *timersModule) luaGet(thr *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
// #property running If the timer is running // #property running If the timer is running
// #property duration The duration in milliseconds that the timer will run // #property duration The duration in milliseconds that the timer will run
// timeout and interval API // timeout and interval API
// The timers interface si one to easily set timeouts and intervals /*
// to run functions after a certain time or repeatedly without using If you ever want to run a piece of code on a timed interval, or want to wait
// odd tricks. a few seconds, you don't have to rely on timing tricks, as Hilbish has a
timer API to set intervals and timeouts.
These are the simple functions `hilbish.interval` and `hilbish.timeout` (doc
accessible with `doc hilbish`). But if you want slightly more control over
them, there is the `hilbish.timers` interface. It allows you to get
a timer via ID and control them.
## Timer Object
All functions documented with the `Timer` type refer to a Timer object.
An example of usage:
```
local t = hilbish.timers.create(1, 5000, function()
print 'hello!'
end)
```
t:stop()
print(t.running, t.duration, t.type)
t:start()
*/
func (th *timersModule) loader(rtm *rt.Runtime) *rt.Table { func (th *timersModule) loader(rtm *rt.Runtime) *rt.Table {
timerMethods := rt.NewTable() timerMethods := rt.NewTable()
timerFuncs := map[string]util.LuaExport{ timerFuncs := map[string]util.LuaExport{