651102 - Document new worker event 'detach'

Status: RESOLVED FIXED

(Add-on SDK Graveyard :: Documentation, defect, P2)

Description

[Alexandre Poirot [:ochameau]]

Attachment: Preliminary doc

A new `detach` event is dispatched on worker object when target document unload. (tab close, window close or document reload)

I sent a first patch that add some lines in worker.md, but I remember that there is others locations to add such documentation ?

Comment 1

[Alexandre Poirot [:ochameau]]

Following bug 607601, we need to document: 
1/ behavior of all Worker objects:
They are destroyed on document unload, it's obvious for page-mod, but it can be more complicated in tab.attach. (if we call attach before the tab is ready, when it loads an about:blank document before the real page)

2/ And they dispatch a new event called `detach` when they are manually or automatically destroyed.

Comment 2

[Alexandre Poirot [:ochameau]]

Attachment: Document `detach` event and worker.destroy

Here is a first step to provide document in interfaces.

Then we will need to add some notes in:
- content script guide to speak about 'detach' event
http://127.0.0.1:8888/dev-guide/addon-development/web-content.html
- page-mod doc to tell that workers are destroyed on tab close or the document is unloaded from the tab [to make it simple, when the location change, but in reality, it's only when document goes out from the bfcache]
http://127.0.0.1:8888/packages/addon-kit/docs/page-mod.html

Comment 3

[Will Bamberg [:wbamberg]]

Attachment: Document worker's detach event in worker and page-mod

> Then we will need to add some notes in:
> - content script guide to speak about 'detach' event
> http://127.0.0.1:8888/dev-guide/addon-development/web-content.html

Hm. I didn't do this because we don't really talk explicitly about worker in that guide, because for the most part worker's APIs are exposed through higher-level APIs.

Apart from listening to page-mod's detach event, are there other obvious applications for detach that need to be captured here?

Comment 4

[Myk Melez [:myk] [@mykmelez]]

Comment on attachment 529757 [details] [diff] [review]
Document worker's detach event in worker and page-mod

r=myk, a=myk for checkin during freeze

Comment 5

[Will Bamberg [:wbamberg]]

Fixed by: https://github.com/mozilla/addon-sdk/commit/3f41c8285b25d3db9b5a0e109c3e5da860c41810

Comment 6

[Myk Melez [:myk] [@mykmelez]]

Cherry-pick to 1.0b5 branch:

https://github.com/mozilla/addon-sdk/commit/d9c48a6f6a4da64c3b4b1f8e76fac8b2f000f36d

Comment 7

[Alexandre Poirot [:ochameau]]

(In reply to comment #3)
> Hm. I didn't do this because we don't really talk explicitly about worker in
> that guide, because for the most part worker's APIs are exposed through
> higher-level APIs.
> 
> Apart from listening to page-mod's detach event, are there other obvious
> applications for detach that need to be captured here?

The only common use case I'm thinking about is `tab.attach` in order to detect location change.

Comment 8

[Alexandre Poirot [:ochameau]]

Comment on attachment 529757 [details] [diff] [review]
Document worker's detach event in worker and page-mod

I forgot to change the flag long time ago.