Manual:IDManager
Introduction
The IDManager is a new item available in Mudlet 4.14+ which allows you to create named tempTimers and event handlers. Mudlet comes with a set of functions for creating named timers and events, and these functions create an IDManager for each "username" that registers one. This page is for if you decide you want direct access to your own IDManager instance rather than letting Mudlet handle it for you. For most people, simply using registerNamedEventHandler(userName, handlerName, eventName, functionReference) and accompanying functions will be sufficient, creating your own IDManager would mostly be for if you prefer an Object Oriented approach to things, or want to build your own functionality on top without using the existing functions as the intermediary.
Motivation
Handling the IDs returned by tempTimer and registerAnonymousEventHandler is some of the most repeated code in Mudlet, and also some of the most frequently forgotten. We get a lot of people through the help channel with duplicated event handlers because they didn't know to capture and kill the previous handler ID first. It's been asked in the past several times if they could provide their own ID. We got asked one too many times and decided to fix it.
Usage
As these are the underlying functions which drive the named timers and event handlers for functions like registerNamedEventHandler, each function will be described and then a link to the corresponding documentation in the main API given. Also, events and timers differ largely in name, so I will cover them in tandem. All examples assume you've created an IDManager and stored it as myIDM.
Creation
Creating a new IDManager is as simple as requesting one from getNewIDManager(). It is recommended you do guard against overwriting these, as they contain all the references to the managed timers and events, and you don't want to lose that.
myIDM = myIDM or getNewIDManager()
Register a new handler or timer
The registration functions return true if the handler or timer was registered successfully, or nil+error if something goes wrong. If you register something to the same name twice, the old handler or timer is killed and reregistered with the new information. This means duplicates with the same name are impossible. Timer names and handler names are checked separately, you can have one of each named "thing".
local ok,err = myIDM:registerEvent("vitals", "gmcp.Char.Vitals", demonnic.handleVitals)
if not ok then
cecho("Something went wrong registering the vitals handler! Panic!\n")
cecho("ERROR was: " .. err)
end
local ok,err = myIDM:registerTimer("balance", 1, demonnic.checkBalance)
if not ok then
cecho("Something went wrong registering the balance timer! PANIC!\n")
cecho("ERROR was: " .. err)
end
Stop a handler or timer
A stopped handler or timer is available to be resumed.
local ok = myIDM:stopEvent("vitals")
if not ok then
printDebug("'vitals' event not registered yet")
end
local ok = myIDM:stopTimer("balance")
if not ok then
printDebug("'balance' timer not registered yet")
end
Resume a stopped handler or timer
Returns false if the handler or timer hasn't been registered yet. If it has, it cancels it if it's running currently and reregisters it with the saved information.
local ok = myIDM:resumeEvent("vitals")
if not ok then
printDebug("'vitals' event not registered yet")
end
local ok = myIDM:resumeTimer("balance")
if not ok then
printDebug("'balance' timer not registered yet")
end
List handlers or timers
Sometimes you want to know what handlers or timers are already registered, whether for display purposes or checking configuration.
local handlerList = myIDM:getEvents()
-- { "vitals" } if only a "vitals" handler has been registered
local timerList = myIDM:getTimers()
-- { "balance" } if only a "balance" timer has been registered
Delete a handler or timer
A deleted handler or timer is gone forever unless reregistered. If you might use it again you may as well stop it instead.
local ok = myIDM:deleteEvent("vitals")
if not ok then
printDebug("'vitals' event not registered yet")
end
local ok = myIDM:deleteTimer("balance")
if not ok then
printDebug("'balance' timer not registered yet")
end
Stop all handlers or timers
You can stop all of your registered handlers or timers at once using these functions
myIDM:stopAllEvents()
myIDM:stopAllTimers()
-- do both in one call
myIDM:emergencyStop()
Delete all handlers or timers
For when you just want to clear it all out and start over.
myIDM:deleteAllEvents()
myIDM:deleteAllTimers()