gecko-dev/js/ref/ChangeLog

Tag JSREF_RELEASE_19980414 (4/14/98):

- RegExp unicode fix.

- Added new iterator-style JSObjectOps enumeration API for host objects.
  See jspubtd.h for details.
	
Tag JSREF_RELEASE_19980413 (4/13/98):

- Date fixes:
  - ECMAv1 fix: fixed function length for Date setters.
  - Bug workaround: avoid MSVC optimizer bug in Date.
  - Y2K fix: Use the verbose '%#c' date formatter for toLocaleString
    on windows, to get a 4 digit date.

- New thread safety fixes from bjorn:

  - Added more asserts to catch cases where the thread
  identifier stored in the context is out of synch with the current
  thread. JS_ATOMIC_ADDREF now calls a function instead of a
  macro, so that when compare-and-swap is implemented using busy-wait
  (e.g. SPARC v8), we avoid being confused by the busy value. For the same
  reason, we now call AtomicRead at certain places in jslock.c. Finally, the
  environment variable JS_NO_THIN_LOCKS, when set, effectively turns off
  the thin locks so that all locking is done using NSPR only.

- ECMAv1 numeric fixes: print preceding 0 when formatting 0.4, ignore supplied
  radix to Number.prototype.toString when printing non-finite numbers.
	
Tag JSREF_RELEASE_19980403 (4/3/98):

- API renaming: JS_NewRuntime for JS_Init, JS_DestroyRuntime for JS_Finish
  (the old names are maintained for backward binary compatibility; the new
  names are macros).

- Improved JS_THREADSAFE locking, with compare-and-swap based optimization of
  the uncontested lock and unlock cases to avoid DLL-crossing and worse native
  OS locking overhead.

  The Request/GC interlock enforced by JS_BeginRequest, JS_EndRequest, JS_GC,
  and JS_MaybeGC allows requests on the same cx to nest (JS_BeginRequest may
  be called more than once before JS_EndRequest, so long as the number of End
  calls matches the number of Begin calls).

  Thread-safety for prarena.c and prdtoa.c, based on jslock.h/JS_THREADSAFE.

- Experimental JS exception implementation, subject to change.  Any value may
  be thrown.  The catch expression must be of the form (v) or (var v).  Catch
  code must re-throw as there is no way yet for the compiler to decide that no
  catch clause matched (and more than one catch clause makes no sense, yet --
  no finally yet, either).

- JS_ConvertArguments API addition, for converting an argc/argv pair according
  to a simplified scanf-like format string.

- JS_GetPropertyAttributes and JS_SetPropertyAttributes API additions, which
  take C-string property names (Unicode string and indexed elements TBD).

- JS_CloneFunctionObject, for server-like environments where code (functions)
  should be shared in a prototype object, but data (global variables) must be
  per request in a set of objects, one per concurrent request.  You load the
  functions in the prototype, then "fault them in" on demand via the request
  object's resolve hook, using JS_CloneFunctionObject to make a lightweight
  copy that has the right scope (__parent__) link.

- Whacked js.c (more whacking needed) so it uses fewer secret js_* calls and
  more JS PUBLIC/FRIEND API entry points.

- Simplified Windows MSDEV build regime to use js.mak/mdp only, which builds
  the DLL as a sub-project, then compiles js.c and links the JS shell.

- Fix a lying comment about JS_AddRoot in README (which is being turned into a
  real "JS API tutorial" document, due soon).

- Better error reporting for an operand that does not convert to function, and
  spiffed up the decompiler (jsopcode.c) to remove hardwired opcode lengths.

- Atom indexing does not abuse the atom's next link and a flags bit, which had
  been done in haste long ago (and not fixed till now), but which required that
  compilation be single-threaded throughout a runtime.

- ECMAv2 change: undefined is a top-level property with undefined value (it may
  be overwritten or deleted by a script).

- ECMAv1 fix: arguments is implemented as a separate object from Call, but with
  Netscape extensions (callee, caller).

- ECMAv1 fix: array length and indexes are uint32.

- ECMAv1 fixes enabled by major overhaul of the compiler to generate a tree of
  parse-node structures and generate code from it.  The bugs had to do with the
  order of evaluation and conversion in for/in loop and assignment expressions.
  This change also moved the "quickening" for name-to-arg/var-slot bytecodes
  from the interpreter to the compiler.

- Proposed ECMAv2 toSource method, which produces compilable object and array
  initializers and new expressions to reconstruct a given graph.

- Proposed ECMAv2 instanceof operator, based on hasInstance JSObjectOp and
  (for maximum code-sharing among native object classes, with one exception)
  JSClass methods.  There is also js_IsDelegate, for checking whether a given
  object is a prototype of another.

- To-be-proposed ECMAv2 in operator, inspired by for/in loop syntax: ('p' in o)
  for o = {p:1} is true; (1 in o) for o[1] defined (even with value undefined)
  is true.  Note distinction between typeof o.p == "undefined" and ('p' in o).

- XDR (eXternal Data Representation) code to support Script.prototype.freeze
  and Script.thaw/Script.prototype.thaw.  You can store a persistent, portable
  encoding of a script (including its top-level functions and all their kids)
  and load it later.

  Exception "try-notes" are not currently XDR'd; this will be fixed next time.

- Recent GC bugs mentioned in snews://secnews.netscape.com/netscape.dev.jsref
  have been fixed.  The patches were posted already; this tarball rolls them
  up along with other fixes and improvements.  We've had help from Netscape's
  Application Products Division in stress-testing this release; we are pretty
  confident that JS_THREADSAFE GC and request execution work well.

  One new fix: finalizers are run without the GC lock held, to allow them to
  call JS_RemoveRoot and otherwise to avoid AB-BA deadlocks.

- Call and construct are now optional methods in JSObjectOps and JSClass.  The
  hack of converting a regexp to a function is no longer necessary, and script
  callability (shorthand for script.exec) uses the JSClass call hook likewise.

- Fixed standard class bootstrapping bug that left an extra Object instance
  in the middle of the prototype chain for Date, RegExp, etc. (all but Object
  and Function) instances.

- String.prototype.split ECMAv1 conformance restoration (split-by-empty-string
  was stupidly broken last time).

Tag JSREF_RELEASE_19980219 (2/16/98):

- Fixed very recent i++ (for undefined i) crash-bug (also prior, longstanding
  bug where i++ for undefined i resulted in NaN).

- ECMA conformance for [[DefaultValue]] (8.6.2.6), ToBoolean (9.2), and null
  (default) this-parameter handling (10.2.3).

- New bytecodes paving the way for ECMA-conformant for/in loops and unqualified
  name assignment.

- JS1.2 String.prototype.replace did not emulate Perl4's expansion of $` to be
  the global left context (not from last local match).  Essentially the same
  bug bit replace for the empty-string global match case, which "bumps along"
  by one character, but failed to include that character in local left context
  (so "abc".replace(/ */g, 'X') produced "XXXX" instead of "XaXbXcX").

- Fix recent regression that clamped String.prototype.split's limit argument at
  the subject string's length.

- Fixed type mismatch problems in #if !JS_HAS_REGEXPS code.

Tag JSREF_RELEASE_19980216 (2/16/98):

- Fixed stuck GC lock by adding JS_UNLOCK_GC at the bottom of js_GC.

Tag JSREF_RELEASE_19980213 (2/13/98):

- Add JS_ShutDown API, which must be called after all JSRuntimes have been 
  destroyed by JS_Finish calls, and from a single thread, when shutting down
  or restarting the program in which JSRef is embedded.  This is needed to
  avoid leaking the deflated_string_cache and (JS_THREADSAFE only) lock.

Tag JSREF_RELEASE_19980212 (2/12/98):

- Finer-grained locking.  Instead of one big, reentrant lock around the entire
  runtime, there are distinct locks:
  - The non-reentrant runtime lock, a binary semaphore to protect the runtime's
    contextList and other members.
  - An atom state lock used only in jsatom.c for a thread-safe internal atom
    table API.  This lock is never held while calling out from jsatom.c to
    other modules that may acquire locks, and no caller into jsatom.c's lock-
    acquiring entry points does so while holding a lock of its own (the GC
    calls non-locking entry points only).
  - A lock and pair of condition variables for interlocking GC execution with
    script execution.  The GC may run only when no script requests are running,
    or when at most one is running and it has invoked the GC from its branch
    callback.  The new JS_SetGCCallback API may be used to supply a function to
    be called at the beginning and end of GC -- if called at the beginning, a
    false return value will cancel the GC run.
  - A reentrant lock per native object map (scope) to protect the JSScope and
    its parts (JSProperty, JSSymbol, and PRHashTable structures) as well as the
    slots vectors of all instances sharing the scope (the prototype object and
    any unmutated clones of it).

  The model jslock.c and jslock.h provided include four new header files that
  are not yet supplied with JSRef:
  - pratomic.h for PR_COMPARE_AND_SWAP_WORDS and PR_COMPARE_AND_SWAP_INT32
    macros that take an address, an old value, and a new value, and return true
    if the old value is at the address, in which case the new value is atomicly
    stored there; and return false without changing memory otherwise.
  - prcvar.h for the PRCondVar condition variable type and its operations (New,
    Destroy, Wait, Notify, and NotifyAll).
  - prlock.h for the PRLock binary semaphore type and its operations (New,
    Destroy, Lock, and Unlock).

  More lock overhead and lock-free synchronization optimizations are coming in
  a future JSRef release.  In anticipation of these changes, the JS_THREADSAFE
  version of JS_GetClass now requires an initial JSContext *cx argument along
  with JSObject *obj.

- New String.prototype.replace feature: a function expression may be passed
  as the second argument, in which case it will be invoked with the match and
  parenthesized submatch strings as arguments, followed by input and index
  (these are come from the extended array returned by RegExp.prototype.exec and
  String.prototype.match).
  
  This "lambda replacement" approximates Perl's s///e flag; the idea came from
  Mike Shaver (shaver@netscape.com).  Here's a example function that replaces
  any number with an F after it (for Fahrenheit) with its Celsius conversion:

  // f2c("32F, 212F, or 0F") => "0C, 100C, or -17.77777777777778C"
  function f2c(x) {
    var s = String(x)
    return s.replace(/(\d+(\.\d*)?)F\b/g,
                     function ($0,$1,$2) { return (($1-32) * 5/9) + "C" })
  }

- First-character discrimination optimization for regular expressions, plus a
  fix to anchor-search for \b and \B.

- A first-class Script object to decompose eval into its compile and exec parts
  (so you can compile outside a long loop, then exec in the loop body to avoid
  recompiling invariant source).  See jsscript.c.

- More ECMA fixes:
  - bitwise logical and shift operators use the correct ECMA type conversions,
    intermediate types, and boundary behavior.
  - Array.prototype.push emulates Perl5 for JS versions other than 1.2; there
    it emulated Perl4, except when no arguments were passed (it would return
    the array object bound to this in that case; fixed to return undefined).
  - All generic Array methods now update a length property, in case no such
    property existed in the object that delegates to Array.prototype, or that
    refers to the particular method.
  - Except for JS1.2, Array.prototype.splice always returns an array, even when
    given no arguments or a zero-length slice.  JS1.2 compatibility continues.
  - NaN Date fixes.
  - JSFunctionSpec's nargs member now species the "best arity" of the function,
    which ECMA specifies as the value of the function's length property.  So to
    allocate local GC roots, use the new extra member of JSFunctionSpec and let
    nargs count only the minimum or optimum number of desired arguments.
  - Relational and equality operator fixes too gnarly and subtle to describe
    here, affecting mainly the hint argument (or lack of it) to valueOf.
  - A new JS_IsConstructing API and underlying support, so ECMA [[Call]] and
    [[Construct]] can be distinguished.
  - A JS_InitClass extension to tolerate NULL for the constructor native C
    function argument -- this causes a class like Math to be created, where
    the class object is not callable or constructable.
  - Fixes to handle non-finite indexes in several string and array methods.

- A high-level object operation dispatch table has been added.  See JSObjectOps
  in jsapi.h, and the new flags and function pointers in JSClass.  To provide a
  table of object operations, your class should set the JSCLASS_HAS_OBJECTOPS
  flag and implement the getObjectOps class method, returning the address of a
  static or otherwise appropriate-lifetime JSObjectOps structure.  The methods
  in this struct will be specified in a forthcoming version of the JS API doc.

  The JSCLASS_NEW_ENUMERATE flag can be used without adding getObjectOps to
  your class, to say that its enumerate method returns a JSIdArray containing
  all lazy and eager property ids for an object, instead of having to define
  all lazily-bound properties in the object, to minimize locking and reduce
  the space cost of old-style enumerate.

- Atoms are now garbage-collected.  To clarify the fact that symbol table ids
  are either tagged jsval-like integers, or else JSAtom pointers, a new typedef
  called jsid (equivalent to jsval in C) has been introduced.

- Major changes to remove JSProperty's object member, in order to optimize for
  space.  These mostly entail an extra &obj2 or &pobj result parameter being
  passed to js_FindProperty, js_LookupProperty, etc., to capture the prototype
  or original object in which the property was found.

- Updated Windows MSDEV makefiles to support MSDEV5.0 as well as 4.2:
  - js32.mak, an NMAKE makefile, builds js32.dll 
  - jsshell.mak, an NMAKE makefile, now recursively invokes js32.mak to build
    js32.dll 
  - jsshelld.mak and jsshelld.mdp, collectively a 4.2 IDE project, build
    jsshell.exe and have a subproject that builds js32.dll.  These two project
    files are not derived from the other .mak files, nor are the other .mak
    files derived from them. 

- JS_PUBLIC_API etc. macros in jspubtd.h, used by jsapi.h and a few other .h
  files, to optimize linkage within the Windows DLL.

Tag JSREF_RELEASE_19971128 (11/28/97):

- Major Unicode changes.  JSString has a jschar *chars member now, not
  char *bytes; it points to a counted array of uint16 (jschar) elements.
  The scanner handles \uXXXX escapes; so does the regular expression parser.

  JS_GetStringBytes(str) now returns the ISO-Latin-1 counterpart of str's
  Unicode sequence by decimating into separate memory whose lifetime matches
  that of str->chars.  The API entry points taking char *name or char *base
  arguments now have UC counterparts (except for the JS_*Property entries)
  that take jschar *name, size_t length or similar argument-pairs.  There is
  a new JS_ValueToUint16 API entry for converting from a jsval to a Unicode
  code point.

- The beginnings of JavaScript 1.3 version support, including === and !== for
  equality by type and value identity, and sharp variables (see below).

- Linux support from Mike Shaver (shaver@ingenia.ca, shaver@netscape.com) in
  config/Linux_All.mk.  OS/2 ifdefs from IBM (initials DSR?), via Dan Libby
  (danda@netscape.com).

- A new gc command in the js shell for testing, useful in conjunction with
  the GC_MARK_DEBUG ifdef'd code in jsgc.c and js.c to plug leaks and find
  stuck references.  Use the new API entry point JS_AddNamedRoot in preference
  to JS_AddRoot, which still exists but provides no debugging name for the GC
  thing graph root that it establishes.  See also JS_DumpNamedRoots.

- JSCLASS_NEW_RESOLVE flag and JSNewResolveOp function pointer typedef, for
  more efficient unbound name resolution.

- Sharp variables (based on Common Lisp's dispatching macros of the same form)
  for expressing cycles and join-points in object graphs created by object and
  array initializers.  For example,

    #1={p:#2={q:42}, r:{cycle:#1#, joinPoint:#2#}}

  creates an object, call it o, where o.p and o.r.joinPoint both reach the same
  object, which has a property named q with value 42; and o.r.cycle is o.

  In a future release, the final JS1.3 version will return object and array
  initializer strings from {Object,Array}.prototype.toSource methods, rather
  than toString, for ECMA and backward compatibility.

- More ECMA conformance fixes, apart from Unicode:
  - New ECMA-conformant jsdate.c by Mike McCabe (mccabe@netscape.com).
  - Improved equality and relational operator implementations.
  - Correct division operator result sign.
  - The unary-plus operator.
  - NaN and Infinity top-level properties.
  - Setting a read-only property fails silently, rather than stopping the
    script with an error report.
  - Deleting a permanent property fails with a false return from the delete
    operator.  If the property is not in the object addressed in the delete
    expression, or it is successfully deleted, the expression results in true.

- The beginnings of finer-grained, non-nesting/low-level locking in jslock.h,
  used in jsstr.c for the deflated_string_cache_lock.  For this version, you
  need to provide a PRLock typedef and PR_NewLock, PR_DestroyLock, PR_Lock,
  and PR_Unlock functions that implement a binary semaphore.

- Performance improvements based on aggressive, coherent use of the property
  cache (part of the JSRuntime structure).  This required a fix to restore a
  watchpoint associated with a deleted property when a new property with the
  same identifier is created in the same object.

- Regular expression bugfixes and Unicode extensions in jsregexp.c and jsstr.c.
  - Fixed Perl bug where \xZ or similar was translated to "\0Z".
  - Fixed another Perl bug where [x-\d] matched {'x', '-', '0', ... '9'} but
    [\d-x] matched only the digits.  The second is now equivalent to the first.
  - Fixed JS bug where only $1 through $9 could be used in the replacement
    string passed to String.prototype.replace.  Also allow literal $ in the
    replacement string if it is preceded by \ (as a JS literal: "\\$").
  - Fixed non-JS1.2 versions to return left context from start of global match
    instead of from end of last local match (Perl4 had a similar bug which 1.2
    emulated too much).  This alters "$`" expansion in replacement strings.

Tag JSREF_1_14_RELEASE (around 7/22/97):

- JSTaskState and related API entry point names have been renamed to use the
  trendier "Runtime" rather than "TaskState", ditto rt or runtime for task.

- JS_GetScriptPrincipals is no longer in jsapi.h, it moved to jsdbgapi.h and
  has a new interface that takes the JSScript * being queried.  It therefore
  requires JS_FrameIterator and JS_GetFrameScript.

- JS_LockGCThing/JS_UnlockGCThing and their macro wrappers JSVAL_LOCK/UNLOCK
  are deprecated as of now.  Use JS_AddRoot to register a pointer to the thing
  you would lock, and clear the pointer and/or JS_RemoveRoot its address later
  to unlock the thing.  I would like to remove GC thing-locking in a future
  release; it precludes too many alternative GC implementations.

- ECMA conformant Date API, including get/setFullYear and the UTC variants
  to all the get/set methods.

- ECMA conformant Number.MIN_VALUE, which is the smallest denorm now, not
  the smallest normal as in all past JS versions.

- ECMA comformant isFinite() function.

- ECMA signed 0 and NaN number to string conversions.

- Watcom (__WATCOMC__) support for PC builds.

Quick update (4/27/97):
- Prototypes are no longer constructed in JS_InitClass.  If you want a class
  prototype to be constructed by the native 'constructor' function passed to
  JS_InitClass, you can save JS_InitClass's return value and do it yourself:

    proto = JS_InitClass(...);
    ok = JS_CallFunctionName(cx, proto, "constructor", argc, argc, &rval);

- Object, array, and function literals are supported on input for JS_VERSION
  1.2 at compile-time.  Only for JS_SetVersion(cx, JSVERSION_1_2) at runtime:
  object.toString() returns an object literal, likewise for array.toString,
  and function.toString returns an anonymous function literall (rather than
  the definition of a function named "anonymous") for functions created using
  new Function(...).

- Final RegExp API: regexp.exec and string.match always return null on mismatch
  (not -1), and always return a match array on match (whether parens matched or
  not).  The match array's 0'th element is the matching string, and any paren
  submatches are in elements 1..N.  The index and input properties can be used
  to find left and right context without resort to the RegExp.leftContext and
  RegExp.rightContext statics:

    leftContext  = match.input.substring(0, match.input.index)
    rightContext = match.input.substring(match.input.index + match[0].length)

- A JS_MaybeGC entry point in the API, safe to use from branch callbacks (well
  tested) and arbitrary preemption points (not so well tested) when garbage may
  be piling up, but a forced GC (JS_GC) is not desirable.

- Various bugfixes and improvements.

Newer news (3/18/97):
- Regular expressions a la Perl are supported.
- Perl array methods push, pop, shift, unshift, and splice are supported.
- Perl substr, with its righteous interpretation of negative offset, is also
  now supported.
- Lexical closures a la Scheme are supported.  See ycomb.js.
- Property caching and other performance improvements have been added.
- Mac CodeWarrior JSRef.prj and MacPrefix.h files are now bundled.
- Windows MSDEV4.2 .mak and .mdp files bundled.
- The 32-bit Windows version of prcpucfg.h is shipped; on Unix platforms, you
  should remove this file or set it aside and let gmake generate the right one
  for your host architecture.
- Classes whose objects have private data (JS_SetPrivate/JS_GetPrivate) must
  flag that fact with the JSCLASS_HAS_PRIVATE flag in their JSClass structs.
- There are also two new property ops in JSClass, addProperty and delProperty.

News flashes (12/31/96):

- Define JS_THREADSAFE and write code in jslock.c for multi-threaded JS.
- NOTE: JS_EvaluateScript and JS_ExecuteScript no longer return a JSVAL_LOCKed
  result in *rval -- this was never safe in a multithreaded environment, when
  *rval referred to an object tree of depth > 1, because a preempting GC run
  could reclaim the unrooted, descendent objects.  Instead, callers of these
  API entry points must use JS_AddRoot and JS_RemoveRoot to maintain the rval
  pointer argument in the GC's root set.  See JS_AddRoot comments below.
- Labeled statements and break and continue to label a la Java are supported.
- The switch statement is now supported.  You can switch on any primitive type
  value (number, string, boolean).
- Numerous performance enhancements, notably the quick ops at the bottom of
  jsopcode.def, have been made.