Using the NIF database back-end

Currently, the Mnesia based back-end is the default, therefore you have to specify a command line argument if you would like to use the NIF based back-end.

After the system is installed, start RefactorErl with

bin/referl -db nif

NIF uses the RefactorErl data directory to store its data. You can specify it by typing

bin/referl -db nif -dir /path/to/your/data/dir

If you would like to start several instances of RefactorErl/NIF, you have to choose different node names. It is also suggested to set different data directories as well, although it is not strictly required.

bin/referl -db nif -sname name1 -dir /path/to/your/data/dir1
bin/referl -db nif -sname name2 -dir /path/to/your/data/dir2

# or

bin/referl -db nif -name name1 -dir /path/to/your/data/dir1
bin/referl -db nif -name name2 -dir /path/to/your/data/dir2

After the system starts up, you can use is it like with the MNESIA database backend, but there are some extra functions. (For further informations see: ri)

Backup-system example

After the system is started, the following operations work on the full database.

% Clear the whole database.
ri:reset().

% Make a checkpoint.
% This operation is always executed after transformations
% and file operations (e.g. adding or dropping a file).
ri:backup().
{ok, backup.1}
% This backup will be created in the directory of the graph
% (./data/graphs/<<graph name>>/).

% Make a checkpoint with a commit log message.
ri:backup("Something log message").

% It will print the following:
{ok, backup.2}
% That 'backup.2' will be created in the same directory as 'backup.1'.

% Now we want to know some informations about 'backup.2'.
% Note: Here you can specify either 'backup.2' or "backup.2" or just 2. 
ri:backup_info(2).
Informations about 'backup.2':
Commit-log: Something log message
Time of creation: Tue Apr 17 11:03:29 2012

% Lists all backups.
ri:ls_backups().

% You can restore a certain backup by specifying it as in ri:backup_info/1.
ri:restore(1).

% Removes all backups.
ri:clean().

Graph operations example

With the NIF database, you may have more graphs. The graphs does not affect each other, so every graph has its own database, and backups, etc. After restarting the tool, the last used graph will be loaded. Let's see an example:

% By default a refactorerl_0 named graph created.
% So after the first start up, the ri:actual_graph/0
% operation should print refactorerl_0. 
ri:actual_graph().
refactorerl_0

% Now create a graph. The name of the graph must be an atom.
ri:create_graph(graph_name).

% You can list the created graphs.
ri:ls_graphs().
[graph_name, refactorerl_0]

% Load the previously created graph.
ri:load_graph(graph_name).
ok
ri:actual_graph().
graph_name

% You may want rename the refactorerl_0 graph to someting else.
% You can even rename the actual graph.
ri:rename_graph(refactorerl_0, some_other_name).
ok
ri:ls_graphs().
[graph_name, some_other_name]

% Now delete the graph which is not loaded.
% Of course, you cannot delete the actual graph.
% Warning: It deletes the whole graph from the disk,
% so it cannot be recovered later.
ri:delete_graph(some_other_name).

% ... or you can just delete all graphs.
% After the deletion, it creates the default refactorerl_0 graph.
ri:delete_all_graphs().
ok
ri:ls_graphs().
refactorerl_0

If something happened to database, then after start up you will get a message about it and a new default graph will be created. If refactorerl_0 exists, then refactorerl_1 will be created, and so on. The corrupted database will not be deleted by the system. If the user wants to load a corrupted backup, then the system will print an error message, and the backup will have a 'corrutped_' prefix (so the system renames it), and the graph will remain the same.

Comparison with the Mnesia back-end

While the Mnesia back-end has been under development longer and can be expected to be more stable, it is much slower than the NIF based back-end; you can expect about an order of magnitude of speed-up. Also, the NIF back-end may require less storage. As an indication, loading ejabberd-2.1.8 (6.6 MB on disk) takes 18323 sec and 566 MB of RAM and 66 MB of disk space, while the NIF back-end on the same machine takes 458 sec and 556 MB of RAM and 52 MB of disk space.