Design rules

This is a summary of the design rules your application has to follow to work with Madeleine.

The Prevalent System

Your objects have to fit into memory

All of them. At the same time.

Your objects have to be marshallable

Snapshots are taken of the system by marshalling the whole system to a file. If your classes can't be marshalled/unmarshalled then Madeleine won't be able to store/restore the system.

Your objects have to be deterministic

Deterministic means that, given the same commands, they have to always give the same results.

For the much of your code this won't be a problem, but there are a few common issues:

The system clock

You can't use the system clock (see instead ClockedSystem and TimeActor).

Random numbers

Kernel.rand() uses the system clock internally by default. Use Kernel.srand() to seed the random number generator before using rand().

Files, network and other IO

You generally can't access the outside world from within your prevalent system. Instead do IO outside of the prevalent system and call into the system when needed.

Changes to the system have to be done through command objects

Everything that modifies the prevalent system must be done through a command object sent to the Madeleine instance, using execute_command(aCommand). Queries that don't modify the system can be done either through direct method calls or through command objects.

Command Objects

A command object is an object that implements the method execute(system). They are an example of the "Command" design pattern.

The command objects also have to be marshallable

Madeleine keeps track of changes between snapshots by logging marshalled commands.

The command must raise errors before modifying the system

Unlike a RDBMS, Madeleine can't roll back a command (yet). This means that your commands will have to do their error checking and raise any errors before modifying the system. Failing to do this will cause an inconsistent command log.

Command objects can't hold references to the system's objects

Unmarshalling such a command would create clones of the original objects, which would then be modified instead of the real objects. The commands must find the objects to modify.