This document describes the internal architecture, organization and design philosophy of the elastiC system. It is aimed at developers wanting to modify or extend the core of elastiC library, which is not an easy task. This is not a necessary reading for module writers or end-users, though it could be an useful aid to a deeper understanding.
elastiC is a complex product, and so its design features many interacting subsystems. It is of fundamental importance to grasp a picture of the interaction patterns of these subsystems. So we'll start by identifying them:
elastiC sources are written following some essential guidelines, that should be observed when making changes or adding functionality. These guidelines try to observe the least surprise principle, in order to minimize the amount of information that the developer has to remember. These conventions have never been written down before, but developed spontaneously from the author mental processes, so it's certain the we'll miss or omit some of them in this short summary, but the developer is encouraged to respect the spirit of the existing sources and to continue in the same direction. We must admit for intellectual honesty that not every part of the source code is strictly adhering to the same conventions (since these changed over time and with author inclinations). The author will be thankful to whom will notify any inconsistency in the existing sources (there are many of them).
elastiC is mainly a library, so it's essential to avoid any pollution of the global name space. The only efficient method to accomplish this in C is resorting to a prefix for every symbol introduced. In elastiC we also use different prefixes to differentiate between classes of symbols, according to the table:
Symbol type | Prefix | Examples |
C macro | EC_ | EC_NULLP(obj), EC_INUM(obj) |
pointer to an elastiC object | EC_ | EC_OBJ (unique) |
Function strongly related to elastiC library | Ec | EcMakeFloat( value ) |
Global C variable for an elastiC object | Ec | EcTrueObject, EcMathErrorClass |
Basic C type wrappers | Ec | EcInt, EcFloat, EcBool, EcChar, ... |
Utility function names & datastructures | ec_ | ec_hash, ec_list_create(), ec_string, ec_mempool, ... |
Function pointers typedefs | ec_ | ec_copy_fcn, ec_mark_fcn, ec_hash_fcn, ... |
Private global variables | _ec_ | _ec_private |
Private functions | _ec_ | _ec_lib_init() |
The reader will notice that some symbols use underscore to separate words and others don't: the rule is that all lowercase names (those with ec_ prefix) use the underscore, the other names use capitalized initials.
elastiC sources are written respecting the following rules:
memcpy( dst, src, nobjs * sizeof(EC_OBJ) );
EC_OBJ EcSendMessage( EC_OBJ obj, EcUInt methodid, EC_OBJ stack ); EC_OBJ EcSendMessageVA( EC_OBJ obj, EcUInt methodid, EcInt nargs, ... ); EC_OBJ EcSendMessageArgs( EC_OBJ obj, EcUInt methodid, EcInt nargs, EC_OBJ *args ); EcSetInstanceVariable( obj, EcParameterCountErrorClass, "expected", expected );
if (condition) { ... } else { ... }
if (! str) return NULL;
switch (condition) { case 0: ... break; case 1: ... break; default: ... break; }
Here we try to analyze in greater depth the major elastiC subsystems. However this guide doesn't pretend to define implementation requirements or standards, so, current source distribution has always the last word in case of ambiguity.
the elastic(1) manpage: for the elastiC language
Marco Pantaleoni (panta@elasticworld.org)
Copyright (C) 2000 Marco Pantaleoni. All rights reserved.
The contents of this file are subject to the elastiC License version 1.0 (the "elastiC License"); you may not use this file except in compliance with the elastiC License. You may obtain a copy of the elastiC License at http://www.elasticworld.org/LICENSE
IN NO EVENT SHALL THE AUTHOR OR DISTRIBUTORS BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY DERIVATIVES THEREOF, EVEN IF THE AUTHOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
THE AUTHOR AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, AND THE AUTHOR AND DISTRIBUTORS HAVE NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
See the elastiC License for the specific language governing rights and limitations under the elastiC License.