105444 - DOM API freeze for Mozilla 1.0

Status: RESOLVED FIXED

(Core :: DOM: Core & HTML, defect)

Description

[Fabian Guisset]

Since the answers to my mail on this subject were rather positive, I'm filing
this bug to be the main placeholder for the DOM API freeze. It's like bug 98278
for XPCOM.
That's where we have a choice: 
1) file separate bugs for each interface (a hassle if you ask me given the huge
number of interfaces we have), like XPCOM does.
2) file separate bugs for each dom/public/idl subdirectory and make them block
this bug
3) Fix everything directly from this bug.

Assigning this to jst, since [e-mail] won't automagically do the job :-O

bz raises a good point: we should make sure that all the interfaces that have
W3C counterparts are exactly like those counterparts.

Does anyone have any requirement as to what is required to freeze an interface?
(wrt comments, owner of the interface, code examples, ...)

Comment 1

[Axel Hecht]

(per category/dir looks good.)
Do we freeze interfaces or contracts? And is stuff like nsIContent part of 
say a nsIDOMElement contract?
Are .h interfaces like nsIContent even part of mozilla1.0 freeze foo?

Comment 2

[Johnny Stenback (:jst)]

Emails (newsgroup postings?) did circulate a while back, but I don't know the
details about how an interface is marked frozen. From what I recall it's a
matter of adding comments to the interface file.

Comment 3

[David Baron :dbaron: (⌚️UTC-4, no longer working on Mozilla)]

Unless nsAString is frozen, a freeze in the C++ DOM api doesn't mean all that
much (except for the methods that don't involve strings).  If you want nsAString
to be frozen, we need to discuss that -- at the current rate of progress, I
think that's not going to happen for 1.0 since I think we need to be using the
new sharable string implementations for a while before we can be confident that
nsAString is what we want.  Are there consumers of the DOM API who want the C++
DOM APIs to be frozen for 1.0, or is this really something that can wait until
later?

Furthermore, I'd like to also propose that we should consider whether C++ binary
compliance with the DOM HTML API is a goal we should have.  If it isn't, we
could probably obtain considerable code-size savings by avoiding all the
forwarding functions to nsGenericHTMLElement from all of the HTML element
implementations.  Even if it is, I think we should measure the size of such
gains before we decide that it's worth it.

Comment 4

[David Baron :dbaron: (⌚️UTC-4, no longer working on Mozilla)]

Oh, and IMO pseudo-COM interfaces like nsIContent and nsIDocument should
definitely not be frozen.

Comment 5

[Johnny Stenback (:jst)]

The target for embedding is indeed to freeze nsAString, but I don't know what
the timeframe is for doing that (Jud, do you know anything more about this?).

I completely agree about *not* freezing internal interfaces like nsIContent and
nsIDocument.

I doubt breaking our nsIDOMHTML* interface compatibility is worth it, it seems
like a forwarding method is ~16 bytes of code (depending on the number of
arguments) plus whatever overhead we'll get per function, plus vtables. A
typical forwarding method (pointer getter) looks something like this on Win32:

  push (this)
  push (retval)
  call (virtual method)
  ret

Assuming we have 2000 of these forwarding methods (rough estimate) times, say 20
bytes per method (maybe this is overly optimistic?), we're paying a ~40k cost in
code size for this, I think that's a price I'm willing to pay for compliance.
And, we can combine more of the rarely used HTML classes (on my todo list),
doing that will make the cost even lower. Maybe my guestimates are overly
optimistic, but I can't imagine them taking up a *lot* of code.

Comment 6

[Johnny Stenback (:jst)]

Pushing to mozilla1.0

Comment 7

[scottputterman]

ADT3 per ADT triage.

Comment 8

[scottputterman]

Changing nsbeta1+ [adt3] bugs to nsbeta1- on behalf of the adt.  If you have any
questions about this, please email [e-mail].  You can search for
"changing adt3 bugs" to quickly find and delete these bug mails.

Comment 9

[scottputterman]

Changing nsbeta1+ [adt3] bugs to nsbeta1- on behalf of the adt.  If you have any
questions about this, please email [e-mail].  You can search for
"changing adt3 bugs" to quickly find and delete these bug mails.

Comment 10

[Johnny Stenback (:jst)]

We're done freezing DOM API's for mozilla1.0, closing bug.