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".

See

registerNamedEventHandler(), registerNamedTimer()

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.

See

stopNamedEventHandler(), stopNamedTimer()

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.

See

resumeNamedEventHandler(), resumeNamedTimer()

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.

See getNamedEventHandlers(), getNamedTimers()

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.

See

deleteNamedEventHandler(), deleteNamedTimer()

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

See

stopAllNamedEventHandlers(), stopAllNamedTimers()

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.

See

stopAllNamedEventHandlers(), stopAllNamedTimers()

myIDM:deleteAllEvents()

myIDM:deleteAllTimers()