Shadow Development Documentation Library Version 5.0 By David Navas Updated: 13 Nov 1992 Copyright © 1992 by David Navas All Rights Reserved GLOSSARY ATTR_* A reference to a particular attribute. An object's attributes are documented in the object's class description in the ShadowLibMethods.doc file. Attribute A variable or structure stored at a particular offset inside of an object. The offset and other information about attributes are stored in the class definition in the class->meta_attributes field. Attributes are qsorted by the unique string address of the attribute (#defined as an ATTR_....) Attributes can also have a default object structure which is the default value (or values for an attribute which is a structure) that all objects containing this attribute take on. All attributes are created by using the AttributeTag structure which is passed into the METHOD_META_SUB or METHOD_META_INIT method defined for METACLASS. Refer to the method definitions in ShadowLibMethods.doc for documentation on these methods. AutoResource An object which has been stuck on a process' ATTR_RESOURCETREE or ATTR_RESOURCESTACK. The ATTR_RESOURCETREE is freed during the process' METHOD_META_REMOVE method, the process' METHOD_META_DESTROY method, and once at the finish of RemoveThread(), or for each ^C received inside of RemoveThread(). The ATTR_RESOURCESTACK is freed only at the finish of RemoveThread(). This implies that the resources on the ATTR_RESOURCESTACK must not reference the process, as RemoveThread() does not get this far until there are no references on a process' object. When these resources are freed, they are sent a METHOD_META_REMOVE and are then dropped from the tree. Notification of this removal is NOT sent. AVL Trees Automatically balancing binary trees which SHADOW uses throughout most of the system. Two notable exceptions are: one, the system string code, and two, the semaphore code. While both of these systems do store various elements on a binary tree, they are NOT AVL trees, and, in fact, the system string code has the right and left child pointer reversed! ;) My A3000 can store and remove about 3500 objects per second from the AVL tree subsystem. These AVL trees are semaphored for correct behaviour in a multi-threaded environment. Binary Trees BinTree See: AVL Trees Browser A cute class browser which allows you to see classes, meta, methods, attributes, and instances of the objects which exist as system elements (ie: objects which have had a METHOD_META_INIT sent to them, but not yet a METHOD_META_REMOVE). Class Used in two ways: First, as an instance of METACLASS. Second, as any formal description of the methods and attributes of an object. For the first, the word should be capitilized: Class. For the second, the word should be lower-case: class, and is often quoted: 'class' Cluster Instance of METACLUSTER. A description whose instances are composites. Describes an object (in particular, a composite) which contains a tree of objects. The Cluster allocates a number of objects to reside initially on those trees when the composite is INIT'd during the METHOD_META_INIT call. Probably obvious, but the Cluster keeps an array of Classes which it instantiates and stuffs into the Composite's ATTR_BAG binary tree. Composite Instance of a Cluster. May want to refer to the docs on the ROOTCLUSTER (ShadowLibMethods.doc). Has an ATTR_BAG attribute which is a binary tree where the composite's objects are stored. Director See: Watcher Inheritence The process by which instances of classes gain the attributes and methods of instances of other classes. In the object- oriented world, this is typically done by sub-classing existing classes. See sub-classing for more details. Instantiation Hierarchy The relationship between an object and its cob_class. An object's cob_class holds a pointer to another object that holds the blueprints to the first object. IE: informally, its class. Under SHADOW, this Hierarchy is a maximum of three objects deep: +----+ | | V | Meta--+ ^ | | Class ^ | | Instance An instance's cob_class points to a Class and a Class' cob_class points to a Meta. A Meta's cob_class points to itself. IE: a Meta describes itself as well as its instances (Classes). Meta A 'class' which is an instance of itself, or (saying the same thing) a meta is a class which describes itself. This is necessary because all classes are an object, and all objects have a descriptive class. When capitilized, it usually refers to a particular meta -- like METACLASS and METACLUSTER. METHOD_* A reference to a particular method. An object's methods are documented in the object's class description in the ShadowLibMethods.doc file. Method A function called as a function or via a message. The function address and other information about methods are stored in the class definition in the class->meta_attributes field. Methods are qsorted by the unique string address of the method (#defined as a METHOD_....) Methods can also be patched, so that one method call might actually end up calling several different functions, in several different ways (via a sybc. message, and via another async call, for instance). All of the patches on all of the methods defined in a particular class are stored in the ATTR_PATCHEDVERBS watched-list. All methods are created by using the MethodTag structure which is passed into the METHOD_META_SUB or METHOD_META_INIT method defined for METACLASS. Refer to the method definitions in ShadowLibMethods.doc for documentation on these methods. Notification The process by which you receive information about changes to Watched Variables. See: Watcher Object Used in three ways: First, as an instance of Class. Second, as an instance of any 'class'. Third, as a package for data. For the first, the word should be capitilized: Object For the second, the word should be lower-case: object The third usage should be apparent. Unfortunately, with the advent of several thousand lines of documentation, it is impossible to ensure that all the documentation uses this guideline. Treat this as a quideline, and not the absolutely authoritative source. Object-Oriented Please see any other book that describes object-oriented programming. The subject is too broad to be covered here. Patch An extra function to be called when the 'patched' method is called. Patches are prioritized, and the normal method is called at patch priority 0. Patch-Chain The list of patches associated with a particular method in a particular class is called a patch-chain. The patches are called from high priority to 0, the regular method is then called, and then the patches with negative priority are called. This behaviour can be modified by the run-time behaviour of patches. Please see The AutoDoc describing DJM() and all the *_BLOCK flags for more details. ppIPC Pete and Peter's Inter-Process Communication library. A very nice port and message implementation which I use. Thanks guys. Property See: Attribute Resource Tracking There are two main types of Resource Tracking. One is for shared objects, and this is the best supported in SHADOW. Please refer to the AutoDocs for UseObject() and DropObject(). The other kind is local resource tracking (resources which go away when a program exits). Please refer to the AutoDocs for AddAutoResource() and RemoveAutoResource(). Resources added using AddAutoResource() are freed automatically when the program exits. You can prevent the removal by calling RemoveAutoResource and managing the returned object yourself. System String System strings are useful for constant strings. The system returns a unique address for a given string, thus allowing the search for a string in, say, an array, by a simple longword comparison, instead of using the slower strcmp() function. sub-classing A sub-class is the result of calling a METHOD_META_SUB on an existing class. The sub-class inherits (or gains) all of the methods and attributes of the pre-existing class, in addition to creating the new attributes and methods that are passed as parameters to the METHOD_META_SUB method. These new methods and attributes replace whatever old descriptions were in the pre-existing class. Under SHADOW, attribute definitions cannot be overrided, although the default attribute object can be. Method definitions can be overrided. The process of creating a sub-class is referred to as sub-classing. sub-meta Same as a sub-class, except that the 'class' that is being 'sub-classed' is actually a meta description. super-class See: sub-class. The pre-existing class becomes the super-class of the sub-class. Tags I use this name in a slightly different manner than AmigaDOS 2.0 does. A 'tagged' array is a NULL-long-word-terminated array where each element is some specific size. For instance, the MethodTag is 24bytes, the AttributeTag is 12bytes. Usually, the First long-word is some kind of specifier. In the case of MethodTag and AttributeTag, these specifiers are pointers to strings. Unique String See: System String Watcher -- WatchedVariable An object which hooks onto a WatchedValue or WatchedTree or WatchedList structure, and gets notification sent to it whenever the watched structure is modified via the *Watch* routines. In particular, whenever the WatcherDispatch function is called. Please see the AutoDocs for this and other *Watch* functions in the ShadowLibFuncs.doc documentation file.