unload
The unload
module allows modules to register callbacks that are called
when they are unloaded. It is similar to the CommonJS module of the same
name in the Narwhal platform.
API Reference
Functions
ensure(object, name)
Calling ensure()
on an object does two things:
- It replaces a destructor method with a wrapper method that will never call the destructor more than once.
- It ensures that this wrapper method is called when
send()
is called.
Therefore, when you register an object with ensure()
, you can call its
destructor method yourself, you can let it happen for you, or you can do both.
The destructor will be called with a single argument describing the reason
for the unload; see when()
. If object
does not have the expected
destructor method, then an exception is thrown when ensure()
is called.
object : object
An object that defines a destructor method.
[ name : string ]
Optional name of the destructor method. Default is unload
.
when(callback)
Registers a function to be called when send()
is called.
callback : function
A function that will be called when send()
is called. It is called with a
single argument, one of the following strings describing the reason for
unload: "uninstall"
, "disable"
, "shutdown"
, "upgrade"
, or
"downgrade"
. (On Gecko 1.9.2-based applications such as Firefox 3.6,
"upgrade"
and "downgrade"
are not available, and "shutdown"
will be sent
in their place.) If a reason could not be determined, undefined
will be
passed instead. Note that if an add-on is unloaded with reason "disable"
,
it will not be notified about "uninstall"
while it is disabled. A solution
to this issue is being investigated; see bug 571049.
send(reason)
Sends an "unload signal", thereby triggering all callbacks registered via
when()
. In general, this function need not be manually called; it is
automatically triggered by the embedder.
[ reason : string ]
An optional string describing the reason for unload; see unload.when()
.