Home | ColdC Language | Genesis | The Cold Dark | History |
Genesis is the ColdC interpreter/driver. A few aspects of ColdC make it unique:
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
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.
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:
To send a signal simply type:
- 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.
Where SIGNAL is one of the above signals, and assuming your log directory is logs (this is the default value).kill -SIGNAL `cat logs/genesis.pid`
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.
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 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).
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.
|