Issue 258 - [Typed objects] Implement a garbage collection mechanism

lib/typedObjects.js

 /*
  * This file is part of Adblock Plus <http://adblockplus.org/>,
  * Copyright (C) 2006-2014 Eyeo GmbH
  *
  * Adblock Plus is free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License version 3 as
  * published by the Free Software Foundation.
  *
  * Adblock Plus is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
@@ skipping 27 matching lines @@
  *
  * The first parameter to ObjectType defines object properties and methods. A
  * name can either be associted with a type (property) or function (method).
  * Numeric value types from the ECMAScript Harmony proposal are predefined as
  * well as "boolean" which is an alias for uint8. In addition to that, already
  * defined object types can be used.
  *
  * The optional second parameter sets type metadata:
  *
  *    constructor: function that will be called whenever an object of the type
- *        is created.
+ *        is created. Parameters supplied during object creation will be passed
+ *        to the constructor.
+ *    destructor: function that will be called when an object of the type is
+ *        freed.
  *    bufferSize: number of objects that should be placed into a single typed
  *        buffer (by default 128).
  *
- * Creating an object instance
- * ---------------------------
+ * Creating and releasing an object instance
+ * -----------------------------------------
  *
  *    var point = Point2D(5, 10);
  *    point.rotate(10);
- *    Console.log(point.x + ", " + point.y);
+ *    console.log(point.x + ", " + point.y);
  *
  * The parameters 5 and 10 will be passed to the constructor function defined
  * for this type.
  *
+ * Once the object instance is no longer needed it should be released:
+ *
+ *    point.release();
+ *
+ * This will not necessarily free the object but merely decrease its reference
+ * count. The object will only be freed when its reference count reaches zero.
+ *
+ * If you need to hold on to an object that you didn't create (e.g. a function
+ * parameter) you have to call object.retain() to increase its reference count.
+ * Once the object is no longer needed you should call object.release().
+ * However, it is preferable to use references from other typed objects to hold
+ * on to an object - the necessary reference count increases and decreases will
+ * be performed automatically then.
+ *
  * Type inheritance
  * ----------------
  *
  *    var Point3D = Point2D.extend({
  *      z: uint32
  *    }, {
  *      constructor: function(super_, x, y, z)
  *      {
  *        super_(x, y);
  *        ...
@@ skipping 24 matching lines @@
 
 function forwardExports(module)
 {
   let moduleExports = require(module);
   for (let key in moduleExports)
     exports[key] = moduleExports[key];
 }
 
 forwardExports("typedObjects/primitiveTypes");
 forwardExports("typedObjects/objectTypes");