Documentation effort magma 0.0.20070911 released magma 0.0.20070829 released magma 0.0.20070806 released on SVN All the news
DOCUMENTATION :: Names
Magma uses some names to indicate well known concepts, just for fun, but sometimes uses some terms for things that need special name. Below is provided a full list of all terms used.
Vulcano
Each Magma node is called "Vulcano". And that's all ;-) Each vulcano is identified by a nickname and a Fully Qualified Domain Name (or an IP address where DNS resolution is unavailable).
Lava (or lava ring)
A lava ring is basically a network of vulcanos (or Magma servers) which agree to export a consistent namespace of flares (see later). Lava ring is associated to a secret passphrase used (well, not yet, but may be in the future) to encrypt network trafic.
Flare (and flare system)
That's the most interesting concept. A flare is everything stored
inside a lava ring. That means that files, directories, symlinks,
character and block devices, FIFOs and sockets are flares.
A flare is described by data structure magma_flare_t
defined in magma_flare.h.
As you can see from the source, there are some common fields, relating
to path, hash of path and so on, and a special union called item
which holds special informations about the flare. A directory will have
a rich item element while a file will not even have one, even
if a magma_flare_file_t structure has been defined (empty).
Flares are saved in a directory passed with -d switch
to magmad. Each flare is contained in a directory named as
the hash of the flare's full pathname, (like
42099b4af021e53fd8fd4e056c2568d7c2e3ffa8
which is the root directory). Inside this directory there are two files
called contents and metadata. The first stores
flare contents, while the second stores informations about the flare
(mainly the struct stat and the full pathname).
When a flare is created from scratch, macro new_flare()
is used. All common fields are allocated, except for the item
field.
A new flare returned by new_flare() macro is not upcasted.
Upcasting a flare is done by flare_upcast() macro, after having
set type of flare in flare's st member. Another way to upcast
flares is to call proper macro, like flare_cast_to_dir() or
flare_cast_to_fifo().
If a flare is successfully upcasted, can be added to internal cache
using magma_add_to_cache() macro and
can be later accessed using cache search function magma_search().
If a magma_flare_t structure is needed even if not upcasted,
is much more comfortable to use magma_search_or_creare().
If flare is not cached, a new unupcasted one is returned. To check if flare
has been upcasted, just read is_upcasted field.
Most special flares are directories which are implemented from scratch
using mmap() syscall. A directory store in its contents
file the names of all entries as a null terminated sequence of names.
For flare system we refer to flares and to code that implements and manages flares, including internal cache mechanism.
