howmanysmall / janitor

Janitor library.

Janitor

Janitor library. This branch is for the thread safe version of Janitor that does not use a global state.

Original was made by Validark, however he doesn't really maintain that version anymore. It does have all the original documentation for it though.

Now on roblox-ts!

Projects that use Janitor

If your project uses Janitor, leave a PR on the readme!

• Armtastic by Mullets Mafia Red
• Be an Alien: Renewal by PeZsmistic
• Benchmarker by boatbomber
• RBLX04 by movsb
• RepoToRoblox by a great friend (boatbomber lol)
• Science Simulator by Interbyte Studio
• Studio Tweaks by PeZsmistic
• Bloopville (NOT RELEASED) by BloopVille Team
• Tropical Town Tycoon by Mightybull Games

Why use Janitor?

• Janitor makes dealing with garbage collection much less annoying and stressful because it manages them all in a nice interface.
• Janitor:Add returns whatever was added, which Maid doesn't.
• Janitor:Add also accepts a custom method, if you want to call :Stop on a Tween. You can see this being used in the JanitorPromise library.
• Janitor:Add also accepts a custom reference to store under, which keeps the api more consistent. (Maid.A = X and Maid:GiveTask(Y) vs Janitor:Add(X, nil, "A") and Janitor:Add(Y))
• Janitor also allows linking to an Instance, so when the Instance is destroyed, the Janitor cleans up everything along with it.

Some less important benefits:

• Runs a little better than Maid does.

Performance

Janitor runs incredibly well. It is quite a bit faster than Maid and around as fast as Dumpster. You can run the benchmark for yourself using boatbomber's benchmark plugin and the bench found here.

Benchmarks ran on an R9 3900X with 32GB of DDR4-3600 RAM.

janitor's Issues

Add `LinkToInstanceRemoval`

This is just a shorthand way of checking if an Instance was removed / parented to nil. This is only being considered because of this information on this tweet, as it's worrying.

function Janitor.__index:LinkToInstanceRemoval(Object, AllowMultiple)
	local function AncestryChanged(_, Parent)
		if not Parent then
			self:Cleanup()
		end
	end

	if AllowMultiple then
		return self:Add(Object.AncestryChanged:Connect(AncestryChanged), "Disconnect")
	else
		return self:Add(Object.AncestryChanged:Connect(AncestryChanged), "Disconnect", LinkToInstanceIndex)
	end
end

Do not use os.clock

os.clock should only be used for it's intended purpose, which is benchmarking as stated on the wiki. It does not reflect upon actual time but rather CPU time - time() is a better alternative for this.

Question: Reasoning behind `:AddPromise()` not having an index parameter?

Hey, I was just wondering what the reasoning was for :AddPromise() not having an index parameter that I can then use when using :Remove()? Genuinely curious as I was about to use it but noticed it didn't have that parameter on the documentation.

Thanks.

Cleanup cleanups that make cleanups

During cleanup, the Maid class will keep iterating throughout all tasks until they are all cleaned up. This takes care of cases where a cleanup function will create another cleanup. Imo, there really shouldn't be cleanup functions making cleanup functions in the first place, but it's a feature to consider.

Cancelling a thread from within itself will error.

A minimum example can be seen here:

const janitor = new Janitor();
janitor.Add(task.delay(1, () => janitor.Destroy()));

@rbxts.janitor.src:612: invalid argument #1 to 'cancel' (thread expected, got nil).

This is because we task.defer the thread cancel, but by this point Object is no longer valid. This could be fixed by checking if Object is still valid before we try to cancel it.

if not Cancelled then
    task.defer(function()
        task.cancel(Object)
    end)
end

My use case here is a thread that I want to end after X amount of time, but I also wish to have the ability to cancel the thread early by name of an event from another place. I want to be able to clear up both the task.delay and the event connection to end this thread early, but the thread will not necessarily be cleaned up early.

Fix `LinkToInstance`

Elttob fixed it for deferred mode.

Refactor Janitor's source code

Currently the source of Janitor is a bit of a mess as I'm pretty much just hacking together things. A full refactor might be in order to make it so the codebase is less hacky.

No deterministic ordering of cleanup functions causes race conditions

Consider a janitor as such

local janitor = Janitor.new()
local camera = workspace.CurrentCamera

-- doing some work which requires custom camera control ...

-- if camera type changes (e.g. corescript), then change to scriptable it
janitor:Add(camera:GetPropertyChangedSignal("CameraType"):Connect(function()
    camera.CameraType = Enum.CameraType.Scriptable
end)

-- reset camera type to custom on cleanup
janitor:Add(function()
    camera.CameraType = Enum.CameraType.Custom
end)

-- stuff  ...

-- no longer need custom camera control
janitor:Cleanup()

depending on the ordering of the cleanup, camera type may end up as Scriptable if the reset function was called before the connection was disconnected. The ideal scenario is that it should always end up as Custom.

This cropped up when converting existing usage of Quenty's maid to janitor, which had deterministic ordering of cleanup.

Cleanup should ideally be applied using a queue or stack based approach. Or alternatively with a priority mechanism.

Issue with closing threads

When I add threads to the janitor, and put the method as true as the documentation says it ends up erroring

energyJanitor.Add(task.defer(() => {
        while (true) {
            task.wait(3)

            if ((zoneEnergy?.GetChildren().size() ?? 0) <= 30) {
                SpawnEnergy(world)
            }
        }
    }), true);

[e-mail]:76: attempt to index thread with boolean

Convert LinkToInstance to use AncestryChanged

sleitnick brought up a good point about the while true do and wait usage in LinkToInstance being an odd choice. AncestryChanged should work the same as well as removing any extra dependencies.

Add support for Quenty's Promise library.

Adding support for Quenty's Promise library would be beneficial if people use both in their codebase.

Here's some example code on how this could be done, although it isn't exactly peak code quality. It could also be separated into two functions, but that would mean extra work on the user's end.

function Janitor.__index:AddPromise(PromiseObject)
	if Promise_is(PromiseObject) then
		if PromiseObject:getStatus() == Promise.Status.Started then
			local Id = newproxy(false)
			local NewPromise = self:Add(Promise.resolve(PromiseObject), "cancel", Id)
			NewPromise:finallyCall(self.Remove, self, Id)
			return NewPromise
		end
	else
		local Promise_isPromise = PromiseObject.isPromise
		if Promise_isPromise and type(Promise_isPromise) == "function" and Promise_isPromise(PromiseObject) then
			if PromiseObject:IsPending() then
				local Id = newproxy(false)
				local NewPromise = self:Add(PromiseObject.resolved(PromiseObject), "Destroy", Id)
				NewPromise:Finally(function()
					self:Remove(Id)
				end)

				return NewPromise
			end
		end
	end

	return PromiseObject
end