Cleanup

Turning things off. One call drops a carrier and everything it subscribed to, and a dropped carrier goes quiet rather than erroring on you.

Destroy Shared

carrier:Destroy() -> ()

Takes no parameters and returns nothing. Works the same on the server and on the client.

local shop = Pigeon.new("Shop")

shop:On("Buy", function(player, itemId)
	print(player.Name, "bought", itemId)
end)

shop:Broadcast("Open", true)

shop:Destroy()

That single call does all of this:

Middleware is cleared for a reason worth saying out loud. A middleware function is a closure you wrote, and it can hold a reference to anything at all. Leaving those on a dead object would keep whatever they captured alive.

Calling it twice is safe

The second call does nothing. Teardowns run once and only once, so you never have to guard it or track whether you already did it.

shop:Destroy()
shop:Destroy()   -- fine, does nothing

A dropped carrier goes quiet

Sending on a dead carrier does not throw. It just does not happen. Teardown often races with work already in flight, and an error there would spread into code that did nothing wrong.

local shop = Pigeon.new("Shop")
shop:Destroy()

shop:Emit("Buy", "sword")             -- nothing happens, no error
local answer = shop:Call("Anything")  -- nil, returns at once, does not yield

Three calls do not stay silent.

The wrong-machine checks still fire. Calling a server method on the client throws ERR_NOT_SERVER whether the carrier is alive or not, and the same the other way round. Being dead does not excuse calling Broadcast from a LocalScript.

It leaves the name cache

Pigeon.new("Shop") with no options hands back a cached carrier. Destroy removes that entry, so the next lookup builds a fresh live one instead of handing you the corpse.

local a = Pigeon.new("Shop")
print(a == Pigeon.new("Shop"))   --> true, same object

a:Destroy()

local b = Pigeon.new("Shop")
print(a == b)                    --> false, b is a new live carrier

Destroying a transformer drops every carrier on it

A transformer is the thing that picks which remote a carrier's traffic rides on. Every carrier that rides on one registers its own teardown there, so destroying the transformer destroys all of them.

local combat = Pigeon.Transformer("Combat")

local damage = Pigeon.new("Damage", { Transformer = combat })
local status = Pigeon.new("Status", { Transformer = combat })
local effects = Pigeon.new("Effects", { Transformer = combat })

-- One call drops all three, with every listener on them.
combat:Destroy()

damage:Broadcast("Hit", 10)   -- goes nowhere, the carrier is inert

This is the tidiest way to turn off a whole feature. Put its channels on one transformer when you build them and you have a single switch later. See Transformers.

Ownership decides which way it runs. A carrier that made its own transformer takes it down with it. A transformer you passed in belongs to you, so carrier:Destroy() leaves it alone.

Staged tables survive

A staged table is not owned by the carrier that published it. The carrier is only a pointer to it. Destroying the carrier stops the replication, but the table object and its contents are untouched.

local scores = Pigeon.StagedTable({ round = 1 })

local old = Pigeon.new("Match")
old:CaptureTable("Scores", scores)

old:Destroy()

-- The data is still there, and a new carrier can publish it again.
print(scores:GetTable().round)   --> 1

local fresh = Pigeon.new("Match")
fresh:CaptureTable("Scores", scores)

What Destroy does to each side:

Turning off one listener instead

Destroy is the big hammer. Most of the time you only want one handler gone, and that is Off.

Off Shared

carrier:Off(event: string, Callback: ((...any) -> ...any)?) -> ()

Returns nothing.

local shop = Pigeon.new("Shop")

local function onBuy(player, itemId)
	print(player.Name, itemId)
end

shop:On("Buy", onBuy)

shop:Off("Buy", onBuy)   -- drop this one handler
shop:Off("Buy")          -- drop every handler for "Buy"

When the last handler for an event is removed, Pigeon drops the underlying transport binding too. So Off is real cleanup, not just a filter. The carrier itself keeps working.

Players who leave clean up on their own

You do not have to do anything when a player disconnects. On the server, Pigeon removes them from every room on the carrier, from the list of players the handshake admitted, and from the subscriber list of every staged table the carrier holds. Anything the server was still holding for that player is thrown away.

A teardown checklist

Tearing down a feature, in order.

1. Disconnect anything you connected yourself. Heartbeat loops, Touched signals, tween completions. Pigeon does not know about those. You can hand them to transformer:Track so they go with the group, which is what Transformer covers.
2. On the client, call Release() on any staged table mirror you no longer want, so the server stops sending you patches.
3. Call Destroy. On the carrier if it is one channel, on the shared transformer if the feature is several channels that belong together.
4. Set your references to nil. The carrier is inert but it is still an object, and something has to let go of it.
5. Do not expect On to work on it afterwards. It registers nothing. See the note below.

Checking nothing leaked

The transport can tell you what it is still holding on this machine. Useful in tests and when you suspect something is not letting go.

Pigeon.Network.Diagnostics() -> {listeners: number, watchers: number, orphaned: number, pending: number, readySeats: number, bufferedPackets: number, readyChannels: number, bufferedChannels: number, outbound: number}

Takes no parameters. Returns one table of counts.

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Pigeon = require(ReplicatedStorage.Pigeon)

local counts = Pigeon.Network.Diagnostics()
print(counts.listeners, counts.pending, counts.bufferedPackets)

These are counts for the whole machine, not for one carrier. After you tear a system down they should settle back to where they were. Queues and pending requests expire on their own, so give it a few seconds before you decide something is stuck.

On after Destroy

What to read next

• Transformers for grouping channels so one call drops them all.
• Known Issues for the sharp edges around teardown.
• Carrier for the full method list.