API Event

For those that don't like images: the wiki has moved to a new place, http://ocdoc.cil.li/.
This wiki will no longer be updated.

---

This API provides a rudimentary event system. It is primarily intended to be used by libraries, to allow them to be notified of signals. For example, this is used to automatically bind the primary screen to the primary GPU, to check whether the terminal is available, and to execute autorun programs on newly installed file systems.

• event.listen(name: string, callback: function): boolean
  Register a new event listener that should be called for events with the specified name. When registering for signal events, this is the name of the signal. Returns true if the listener was successfully registered, false if it already was registered for this event type.
  Note that event listeners may return false to unregister themselves (equivalent to calling event.ignore and passing the listener with the event name it was registered for).
• event.ignore(name: string, callback: function): boolean
  Unregister a previously registered event listener. Returns true if the event listener was removed, false if the listener was not registered.
• event.timer(interval: number, callback: function[, times: number]): number
  Starts a new timer that will be called after the time specified in interval. Per default, timers only fire once. Pass times with a value larger than one to have it fire as often as that number specifies. Pass math.huge to create an infinitely repeating interval.
  This returns a number that identifies the created timer, and can be used in timer.cancel to destroy it, possibly before it even ran once.
  Note: the timer resolution can vary. If the computer is idle and enters sleep mode, it will only be woken in a game tick, so the time the callback is called may be up to 0.05 seconds off.
  Important: timers are driven by the event.pull function. If you always pull signals directly from os.pullSignal and never call event.pull, timers will not work!
• event.cancel(timerId: function): boolean
  Cancels a timer previously created with event.timer. Returns true if the timer was stopped, false if there was no timer with the specified ID.
• event.pull([timeout: number], [name: string], ...): string, ...
  This, besides os.sleep() should be the primary way for programs to "yield". This function can be used to await signals from the queue, while having unrelated signals dispatched as events. It also drives timers created with event.timer, so it should be called regularly anyway.
  If the first parameter is a number, it is expected to be the time to wait for the signal, before returning nil, the second parameter then has to be the event name. Otherwise the first parameter has to be the event name. The event name can be nil, however, to not filter for a specific event.
  Any further parameters are used as a direct filter. The function will only return events that match this filter - meaning the parameters are equal to those provided in the filter (direct equality for all parameters, regular expressions are possible for the event name, see string.match).
  For example, the click signal (when a player clicks on a tier two or three screen) has the signature screenX: number, screenY: number, playerName: string. To only pull clicks by player "Steve" you'd do: local _, x, y = event.pull("click", _, _, "Steve")
• event.shouldInterrupt(): boolean
  This function is called by event.pull after each signal was processed, to check whether it should abort early. If this returns true, event.pull will throw an interrupted error.
  Per default, this returns true if the combination Ctrl+Alt+C is pressed.
• event.onError(message: any)
  Global event callback error handler. If an event listener throws an error, we handle it in this function to avoid it bubbling into unrelated code (that only triggered the execution by calling event.pull). Per default, this logs errors into a file on the temporary file system.

This example will check if the computer has been running for over 300 seconds every 30 seconds, and if it has, it reboots it:

local computer = require("computer")
local event = require("event")

function onTimer()
    computer.shutdown(true)
end
event.timer(30, onTimer, 50) --run 50 times, then stop. If it's still not past 300 seconds by then, we've got other things to worry about.