the Cold Software Project

Genesis is the ColdC interpreter/driver. A few aspects of ColdC make it unique:

  1. Persistence - every object instance is also a class, and inherently persistent in a database
  2. Run-Time Mutability - Object methods can be updated during runtime.
  3. Although object oriented also has a strong functional language influence.

This model lends itself to online services which require strong persistence.

Download the last stable 1.1.12 [links to a tar.bzip file]
Dev Branch at Github Repo

ColdC / Genesis Features

The Cold Project manages evolution and development of ColdC and Genesis, a ColdC driver. ColdC is an Object Oriented database server language originally engineered by Greg Hudson with influences from C, MOO and CoolMUD.

Disk based database
Because the database is disk based, only the currently active objects will be in memory. This means you driver will not bloat into large virtual memory pages.
Efficient interpreter
The interpreter for ColdC is engineered for speed by using abstract representations of data (hashes) rather than manipulating string after string directly.
Easily Extendable
Genesis allows for additions of Native Methods to objects through a simple module system. This means you can optimize your database as needed. Furthermore, it also allows for easy additions of new data types.
Multiple Inheritance
ColdC allows for multiple parents per object.
Powerful Networking
ColdC gives the ability to easily handle multiple incoming and outgoing connections. You are not restricted to a single connection port--instead you can have multiple ports for each service.
Language Encapsulation
ColdC has a high defined role for data encapsulation and modularity.
Server Role Abstraction
The server does not try to manage your database, it simply interprets ColdC. It does not handle permissions, command parsing nor anything else. It simply knows of a connection and sends the input and output to and from the connection respectively. Because of this the same driver has successfully been used to write MUDs and dynamic WWW servers.
Asynchronous Backups
Database backups are done asyncronously, while your system is still functioning as normal.
Dynamic Text
ColdCore defines ctext which is an internal abstraction of text. Using ctext ColdCore can quickly parse a document to HTML, Plain-Text or any other text format you desire.
Multi-Platform Support
Genesis compiles with ease on nearly all modern unix and Win32 systems.

Genesis Administration

Genesis was initially created as ColdMUD by Greg Hudson, and was later engineered by other individuals, being finalized by Brandon Gillespie.

Introduction

Genesis consists of the programs coldcc, genesis and control. coldcc is used to compile/decompile the database between textual and binary forms. It is also used for external binary database manupulation (such as adding objects, fixing methods, etc). genesis is the run-time interpreter of a binary database. control is not used at the moment.

Several variables are common to all programs:

Base Directory

The base directory is where programs will start to look for files and other directories. This is commonly named world, although it's name is irrelevant as long as the programs know what it is. Unless you explicitly tell a program what the base directory is, it will assume the base directory is the current directory (i.e. the directory you are in when you execute the program).

Binary Database Directory

The binary database directory is where the database files are located, do not specify a directory already used by other files as this directory! When the binary database is compiled coldcc will unlink and destroy any existing files, in an existing binary directory, or it will create it if it does not exist. This entire directory is also copied when a backup is performed (with the ColdC function backup()).

If unspecified, the binary database directory will be binary in the base directory.

Logfile Directory

If the program logs information, it will attempt to open it's logfile in the Logfile Directory. If unspecifiedk, the logfile directory will be logs in the base directory. The logfile directory will not be created if it does not exist. When programs start logfiles are opened for appending, any log information will remain with the new log information appended to the end.

DB Root File Directory

If the programs were compiled with RESTRICTIVE_FILES enabled, files may only be read and written to within the database root file directory. Unless otherwise specified this directory will be root in the base directory.

DB Executable Directory

The database executable directory is for programs to be executed from ColdC with the execute() function. Unless otherwise specified this directory will be dbbin in the base directory.

Database Versions

It is important to remember that a binary database may ONLY be interpreted with the same executable that created it. Because the byte codes can change from compile to compile (adding/removing modules can change these), the binary database will be different. It is important to remember this when upgrading or adding/removing modules to a database. Always decompile a database to text first, then recompile the database with the new coldcc.

Compiling/Decompiling a database

The simplest way to compile a text database is to enter the base directory and run coldcc, specifying the textdump to read. If the textdump is named textdump you do not need any additional arguments, as this is what coldcc expects. Otherwise use the -t name flag (where name is the name of the textdump). For instance, if your text database was minimal.db you would type:

coldcc -t minimal.db

The simplest way to decompile a binary database is to enter the base directory and run coldcc with the argument flag -d. It will decompile the binary database in the directory binary. If you have a different binary directory name you can specify it with the flag -b name. The text database will be named textdump, unless you use the flag -t name.

Running the driver

The simplest way to run the driver on a binary database is to enter the base directory and run genesis. genesis will automatically fork off and run in the background (if you do not want it to fork off, run it with the flag -f). If the logfile directory exists logged information will be printed to the following files in the logfile directory:

db.log
driver.log
genesis.pid

db.log is the logfile for the database. Information is written to this file with the ColdC function log(). driver.log is used by the driver for messages which are not related to the run-time environment (such as reporting a signal). genesis.pid contains the process id for the currently running driver. This can be used to shutdown a server.

Shutting down the server

The server can be shutdown two ways. Either by calling the ColdC function shutdown(), or by sending a signal to the driver process.

Signals

Genesis catch and handle several signals. Signals can be sent to a process in unix with the command kill. When a signal is caught by genesis the method signal is called on the system object. If a database wishes to perform an action when a signal is caught it may by hooking into this method.

The following signals are caught by genesis, handled as specified, then sent to the database by calling the signal method on the system object:

HUP
Sending this signal will flush all connection and file buffers, and will push the interpreter into non-atomic mode, if it is running atomically.
FPE
FPE signal is converted to an ~fpe error for the task which caused it. No message is sent to the database for this signal.
USR1
This causes the driver to cancel all tasks (currently running, preempted and suspended) and return to execution as normal. This is not normally suggested, as it can throw off a database's normal execution situation. However, it is useful when a task has run out of control and is consuming resources.
USR2
genesis does nothing with this signal.
KILL
If this signal is caught genesis will panic and shutdown. No message is sent to the database for this signal.
CHLD
PIPE
These signals are used for internal processing, and are not sent to the database.
QUIT
The system will attempt to shutdown, currently running processes will continue to completion, and a message is sent to the database.
INT
TERM
The first time any of these signals are received all tasks are aborted (suspeded or otherwise), and the system attempts to shutdown. If these signals are received again the driver will panic. No message is sent to the database for these signals.
To send a signal simply type:
kill -SIGNAL `cat logs/genesis.pid`
Where SIGNAL is one of the above signals, and assuming your log directory is logs (this is the default value).

Using a Binary Database

You will want to be VERY careful not to run from a corrupt binary database. It is possible to work around the locks on a binary database which tell genesis and coldcc its status. Do not do this! If genesis reports the binary database as being corrupt, it is! Many people have found that genesis will run from a corrupt db, if you diddle with some files. However, this is not a stable base to build upon, as the moment genesis reaches corrupt data in the database everything will crash, possibly corrupting even more data. The suggested course of action when you have a corrupt binary database is to simply run from a backup. If you do not have a backup then attempt to decompile the corrupt database with coldcc.

NFS

Running the binary database from an NFS disk is NOT SUGGESTED. You will run into lag problems if you do this, even more notably when a backup is running. If possible some lag can be alleviated by soft linking 'binary.bak' to a local drive, for backups (such as /tmp/binary.bak). Overall this is simply not suggested.

Backups

You can expect the backup to take approximately one second for every megabyte in your binary database (it will be faster or slower depending upon your computer and the speed of your disk). Most of this is asyncrynous-- you are still running while it is backing up. There will be a slight pause of all tasks in the server when the backup is initialized. The length of this pause will depend upon how large your cache is, and how many active objects are in memory. In general this pause will be around one second as the cache is cleaned. It has been tested on a large cache of 40x50 (2000 objects in cache) with many active objects. The initial pause takes about three seconds with this configuration.

Genesis Copyright

ColdMUD is copyright 1993, 1994 by Greg Hudson

Genesis is authored by many people, and is Copyright 1994, 1995, 1996 by Brandon Gillespie, unless otherwise stated in an individual file.

The following terms apply to all files associated with Genesis unless explicitly disclaimed in an individual file.

The authors hereby grant permission to use, copy, modify, distribute, and license this software and its documentation for any purpose, provided that existing copyright notices are retained in all copies and that this notice is included verbatim in any distributions. No written agreement, license, or royalty fee is required for any of the authorized uses. Modifications to this software may be copyrighted by their authors and need not follow the licensing terms described here, provided that the new terms are clearly indicated on the first page of each file where they apply.

IN NO EVENT SHALL THE AUTHORS 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 AUTHORS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. I.E. IF THIS SOFTWARE MAKES YOUR COMPUTER EAT YOUR HARD DRIVE, IT IS NOT OUR FAULT.

THE AUTHORS 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 AUTHORS AND DISTRIBUTORS HAVE NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.

Genesis Credits

Genesis is a derivitive work of ColdMUD. The concise history of it, from ColdMUD, can be found in the CHANGES file. The name change is to make a distinction between the developmental time Greg Hudson spent (versions 0.0 through 0.10)--followed by various changes from a few contributors, including Greg Hudson (versions 0.11 and 0.12)--and those made under the management of the Cold Project.

The Cold Project is a conglomeration of programmers dedicated to advancing the driver and any relative databases.

The Cold Project is a free softare organization. If you enjoyed software the project distributes and/or maintains, donations of any type to continue their existance will be accepted. Donations may be made anonymously. All donations are used to continue and extend the Cold Project (The Cold Project maintains a server for development and distribution. Donations are regularly used in maintaining and improving the server. Hardware and monetary donations are both encouraged).

ColdMUD Credits

This program borrows many ideas from LambdaMOO, written by Stephen White and Pavel Curtis, and COOLMUD, written by Stephen White.

The database routines in this code originate from code by Marcus J. Ranum, although only the block allocation algorithm is currently similar to his code. The cache algorithm also uses his ideas.

The regular expression matcher used by Coldmud (regexp.c) was written by Henry Spencer.

Numerous people have contributed valuble ideas and debugging effort. Among them are Jay Carlson, Erik Ostrom, Matthew Rhoten, Loyd Blankenship, Gregory Blake, Jeff Prothero, Nils McCarthy, Brandon Gillespie, Ron Strait, Alex Stewart, Jordan Baker, Ryan Daum, Doug Orleans, Matthew Gray, and Scott Dickenshied.

Copyright © 2017 Brandon Gillespie