jQuery Callbacks lock() Method

What You’ll Learn

The lock() method freezes a Callbacks list in its current state — no more add(), remove(), or empty() — while fire() still runs registered handlers. This tutorial covers syntax, five examples, and how lock() differs from disable().

Introduction

During plugin setup or event wiring, you often register handlers with add(). But once initialization is complete, you may want to prevent late code from adding or removing subscribers — while still allowing fire() to notify everyone already on the list.

lock() does exactly that. It snapshots the handler queue and blocks further mutations. The old reference incorrectly described lock() as blocking callback invocation or providing a “release” mechanism — jQuery’s lock() is about freezing the list, not pausing fire().

Understanding the lock() Method

callbacks.lock() locks the Callbacks list in its current state. After locking, mutating methods — add(), remove(), and empty() — silently do nothing. Handlers registered before the lock remain and still run when you call fire() or fireWith().

There is no unlock() method. Once locked, the list stays locked for the lifetime of that object. Use locked() to check whether locking has occurred.

📝 Syntax

General form of callbacks.lock:

callbacks.lock()

Parameters

• None.

Return value

• Returns the same Callbacks object (chainable).

Basic pattern

const callbacks = $.Callbacks();



callbacks.add(function () { console.log("Registered"); });

callbacks.lock(); // freeze the list



callbacks.add(function () { console.log("Too late"); }); // ignored

callbacks.fire(); // → Registered

Examples Gallery

Each example shows a different aspect of locking a Callbacks list.

const callbacks = $.Callbacks();



callbacks.add(function () {

  console.log("First callback executed.");

});



callbacks.lock();



callbacks.add(function () {

  console.log("Second callback executed.");

}); // silently ignored



callbacks.fire(); // only first handler runs

First callback executed.

const callbacks = $.Callbacks();



callbacks.add(function (n) {

  console.log("Tick:", n);

});



callbacks.lock();

callbacks.fire(1);

callbacks.fire(2); // both fires succeed

Tick: 1

Tick: 2

const callbacks = $.Callbacks();

const handler = function () { console.log("Still here"); };



callbacks.add(handler);

callbacks.lock();

callbacks.remove(handler); // ignored

callbacks.fire();          // → Still here

Still here

const locked = $.Callbacks();

locked.add(function () { console.log("locked: fired"); });

locked.lock();

locked.fire(); // → locked: fired



const disabled = $.Callbacks();

disabled.add(function () { console.log("disabled: fired"); });

disabled.disable();

disabled.fire(); // nothing

locked: fired

const Plugin = (function () {

  const hooks = $.Callbacks();



  return {

    onReady: hooks,

    init: function () {

      hooks.add(function () { console.log("Core ready"); });

      hooks.lock(); // registration closed

      console.log("Init complete — hooks locked");

    },

    run: function () { hooks.fire(); }

  };

})();



Plugin.init();

Plugin.onReady.add(function () { console.log("Too late"); });

Plugin.run();

Init complete — hooks locked

Core ready

🚀 Use Cases

• Plugin init — close registration after setup completes.
• Deferred-style flows — lock callback queues before resolving (jQuery uses this internally).
• Immutable subscriber sets — guarantee the handler list cannot change at runtime.
• Defensive APIs — prevent third-party code from removing core handlers.
• Testing — assert locked() is true after a lifecycle milestone.

📝 Notes

• lock() blocks mutations, not fire() or fireWith().
• There is no unlock() — locking is permanent for that list object.
• Check status with locked(), not disabled().
• disable() is stronger — it prevents firing and clears internal state.
• Call lock() only after all intended handlers are registered.

💡 Best Practices