Cleaning up
A function joined to an event keeps running every time the event happens, until it is taken off again. A part of a script that starts something (a listener, a task, a few things of its own) usually has to stop all of it later, and it is easy to forget one. A maid remembers for you: give it everything that has to go together, and clean cleans it all up in one call.
local scored = signal.new()
local events = maid.new()
events:give(scored:connect(function(points)
print("scored", points)
end))
scored:fire(3)
wait()
events:clean() -- the listener is taken off: scored can fire, nothing hears it
scored:fire(4)It prints
scored 3A signal's functions do not run the moment it is fired: they run a moment later, when the script next waits or ends (see Events). So a function that was already waiting its turn when clean() took it off still runs, once:
local scored = signal.new()
local events = maid.new()
events:give(scored:connect(function(points)
print("scored", points)
end))
scored:fire(1)
events:clean() -- too late for the 1: it was already on its way
scored:fire(2) -- nothing hears this one
wait()It prints
scored 1What a maid takes
events:give(what) takes anything that can be cleaned up, and cleans each the way it should be:
| Given | Cleaned up by |
|---|---|
| a connection | taking it off (connection:disconnect()) |
| a function | calling it |
| a thing | destroying it |
a task (task.spawn, task.delay) | stopping it |
| a shader | removing it |
| a looped sound | stopping it |
| another maid | cleaning it |
a table with a destroy function | calling destroy |
give gives back what it was given, so a thing can be made and handed over in one line:
local stuff = maid.new()
local spark = stuff:give(things.new(cat.Kind.decoration, { name = "Spark" }))
spark.alpha = 0.5clean cleans the last thing given first, and leaves the maid empty: it can be given more and cleaned again.
Names
Something given with a name can be found, cleaned or taken out by that name. Giving a name that is taken cleans what had it first, which is handy for "only one of these at a time":
local music = maid.new()
music:give(sound.loop("@coin"), "song")
music:give(sound.loop("@door"), "song") -- the first loop is stopped
print(type(music:get("song")))
music:clean("song") -- just that onemusic:take("song") takes something out without cleaning it, and gives it back. music:all() lists everything the maid holds, in the order it was given.
keep works the other way round: it cleans everything except what was given under the names you list, the last given first, and what is kept stays in the maid. Something given with no name is always cleaned. With no names at all, keep() keeps nothing, so it cleans everything as clean() does.
local stage = maid.new()
stage:give(function() print("music off") end, "music")
stage:give(function() print("lights off") end, "lights")
stage:give(function() print("door shut") end)
stage:keep("music")
print(#stage:all())It prints
door shut
lights off
1Cleaning up later
Some things should only last a while: a spark that fades, a listener for the next few seconds. giveFor gives something to the maid as give does, with a number of seconds after it. When that time is up, the maid cleans it by itself. The script does not stop to wait for that: it carries on with the next line.
local sparks = maid.new()
sparks:giveFor(function() print("spark gone") end, 0.5)
print("given")
wait(1)
print(#sparks:all())It prints
given
spark gone
0Like give, it gives back what it was given, and a name can come after the seconds: sparks:giveFor(spark, 2, "big"). If it is cleaned or taken out before its time (by clean, keep, take, destroy, or a give with the same name), nothing more happens to it when the time comes.
cleanAfter does the same for the whole maid: after that many seconds, it cleans everything it holds then, as clean() would. It does not destroy the maid, so the maid can be given more afterwards. destroyAfter destroys the maid after that many seconds instead, as destroy() would. Both give back a task, and task.cancel stops it before its time. If the maid is destroyed first, nothing happens when the time comes.
local hint = maid.new()
hint:give(function() print("hint hidden") end)
local timer = hint:cleanAfter(3)
task.cancel(timer) -- not that one after all
hint:destroyAfter(0.5)
wait(1)It prints
hint hiddenCleaning when a thing goes
cleanWhenGone ties a maid to a thing: when the thing is destroyed (or its time is up), the maid is cleaned. It is the easy way to make what belongs to a thing go with it. Give it one thing per maid: when that thing goes, the whole maid is cleaned, not only what was given for it.
local door = things.find("Door")
local own = maid.new()
own:give(level.beat:connect(function()
door.alpha = 1 - door.alpha
end))
own:cleanWhenGone(door)When a maid is not needed any more at all, destroy cleans it and ends it: giving it more is then a mistake.
Knowing when it cleans
Every maid has two events of its own. cleaned happens each time the maid has cleaned something up: after clean, keep, cleanAfter, cleanWhenGone and destroy, when the time of something from giveFor comes, and when give takes a name from something. If there was nothing to clean, it does not happen. destroyed happens once, when the maid is destroyed. Neither gives its functions any values.
local round = maid.new()
round.cleaned:connect(function() print("cleaned") end)
round.destroyed:connect(function() print("destroyed") end)
round:give(function() print("round over") end)
round:destroy()
wait()It prints
round over
cleaned
destroyedWhen a maid is destroyed, it first cleans what it holds (so cleaned happens, if it held anything), then destroyed happens, and after that both events are over: whatever was connected to them is disconnected, and asking a destroyed maid for one of them is a mistake. Only the maid makes its events happen: round.cleaned:fire() is a mistake too.
Safe to use
A cleanup that fails is said in the script output (in yellow), and the others are still cleaned. A maid can't be given to itself, and two maids that hold each other clean up once each. A function connected to cleaned may clean the same maid again: once it is empty there is nothing to clean, so cleaned does not happen again. type(events) is "maid", so events is maid asks whether a value is one.