diff --git a/Doc/internals.html b/Doc/internals.html index 5a599e084..9ea9e9214 100644 --- a/Doc/internals.html +++ b/Doc/internals.html @@ -9,7 +9,11 @@ Thien-Thi Nguyen
ttn@glug.org
-(with much help from others)
+ +

+David M. Beazley
+beazley@cs.uchicago.edu
+
@@ -201,7 +205,217 @@ which uses the callbacks registered by SWIG_main() above.

2. DOH

-[TODO] +DOH is a collection of low-level objects such as strings, lists, and +hash tables upon which the rest of SWIG is built. The name 'DOH' +unofficially stands for "Dave's Object Hack", but it's also a good +expletive to use when things don't work (as in "SWIG core +dumped---DOH!"). + +

2.1 Motivation and Background

+ +The development of DOH is influenced heavily by the problems +encountered during earlier attempts to create a C++ based version of +SWIG2.0. In each of these attempts (over a 3 year period), the +resulting system always ended up growing into a collossal nightmare of +large inheritance hierarchies and dozens of specialized classes for +different types of objects (functions, variables, constants, etc.). +The end result was that the system was tremendously complicated, +difficult to understand, difficult to maintain, and fairly inflexible +in the grand scheme of things. + +

+DOH takes a different approach to tackling the complexity problem. +First, rather than going overboard with dozens of types and class +definitions, DOH only defines a handful of simple yet very useful +objects that are easy to remember. Second, DOH uses dynamic +typing---one of the features that make scripting languages so useful +and which make it possible to accomplish things with much less code. +Finally, DOH utilizes a few coding tricks that allow it to perform +a limited form of function overloading for certain C datatypes (more +on that a little later). + +

+The key point to using DOH is that instead of thinking about code in +terms of highly specialized C data structures, just about everything +ends up being represented in terms of a just a few datatypes. For +example, structures are replaced by DOH hash tables whereas arrays are +replaced by DOH lists. At first, this is probably a little strange to +most C/C++ programmers, but in the long run in makes the system +extremely flexible and highly extensible. Also, in terms of coding, +many of the newly DOH-based subsystems are less than half the size (in +lines of code) of the earlier C++ implementation. + +

2.2 Basic Types

+ +The following built-in types are currently provided by DOH: + + + +Due to dynamic typing, all of the objects in DOH are represented by pointers +of type DOH *. Furthermore, all objects are completely +opaque--that means that the only way to access the internals of an +object is through a well-defined public API. For convenience, the following +symbolic names are sometimes used to improve readability: + + + +It should be stressed that all of these names are merely symbolic aliases to the +type DOH * and that no compile-time type checking is performed (of course, +a runtime error may occur if you screw up). + +

2.3 Creating, Copying, and Destroying Objects

+ +The following functions can be used to create new DOH objects + + + +Any object can be copied using the Copy() function. For example: + +
+
+DOH *a, *b, *c, *d;
+a = NewString("Hello World");
+b = NewList();
+c = Copy(a);         /* Copy the string a */
+d = Copy(b);         /* Copy the list b */
+
+
+ +Copies of lists and hash tables are shallow. That is, their contents are only copied by reference. + +

+Objects can be deleted using the Delete() function. For example: + +

+
+DOH *a = NewString("Hello World");
+...
+Delete(a);              /* Destroy a */
+
+
+ +All objects are referenced counted and given a reference count of 1 when initially created. The +Delete() function only destroys an object when the reference count reaches zero. When +an object is placed in a list or hash table, it's reference count is automatically increased. For example: + +
+
+DOH *a, *b;
+a = NewString("Hello World");
+b = NewList();
+Append(b,a);         /* Increases refcnt of a to 2 */
+Delete(a);           /* Decreases refcnt of a to 1 */
+Delete(b);           /* Destroys b, and destroys a */
+
+
+ +Should it ever be necessary to manually increase the reference count of an object, the DohIncref() function +can be used: + +
+
+DOH *a = NewString("Hello");
+DohIncref(a);
+
+
+ +

2.4 A Word About Mutability and Copying

+ +All DOH objects are mutable regardless of their current reference +count. For example, if you create a string and then create a 1000 +references to it (in lists and hash tables), changes to the string +will be reflected in all of the references. Therefore, if you need to +make any kind of local change, you should first make a copy using the +Copy() function. Caveat: when copying lists and hash tables, elements +are copied by reference. + +

2.5 Strings

+ +The DOH String type is perhaps the most flexible object. First, it supports a variety of string-oriented +operations. Second, it supports many of the same operations as lists. Finally, strings provide file I/O +operations that allow them to be used interchangably with DOH file objects. + +[ TODO ] + +

2.6 Lists

+ +[ TODO ] + +

2.7 Hash tables

+ +[ TODO ] + +

2.8 Files

+ +[ TODO ] + +

2.9 Void objects

+ +[ TODO ] + +

2.10 Utility functions

+ +[ TODO ]

3. Types and Typemaps