Class loading

The class loading algorithm

How must the source files be named?

The algorithm used by Liberty to look for an Eiffel source file is the following:

1. Lower case filenames - Liberty looks all along the loading path (see below) using the class name in lower case as prefix. If needed, the Eiffel suffix (".e") is added automatically. Liberty only looks for suffixed files on the disk. Only the first file encountered according to the order of the path is taken in account. An Eiffel file is always supposed to have the same name as the inside class definition.
2. Upper case filenames - When the previous step did not find the required Eiffel class file, Liberty looks along the loading path (see below) for a file bearing the class name upper in upper case letters. If needed, the Eiffel suffix ".e" is added automatically. One must note that the overhead to find an upper case file name is not negligible at all, and that a lower case file name may hide some upper case name.

How is the loading path built?

As described above, Liberty looks for classes in .e files. But where should those files be situated? The answer is, in the loading path. The thing is, how is the loading path built, what are the default values, and how can it be changed?

Liberty builds a "universe" where it looks for all the classes. This "universe" is a tree of clusters. The root of the tree is the universe. This universe is either made of clusters and loadpath.se files provided by:

• either the ACE file
• or a combination of the following:
  • the command line (-loadpath arguments)
  • the current directory (a loadpath.se file in the current directory if it exists, the cluster represented by the current directory otherwise)
  • the configuration file

Each loadpath.se file is a node of the tree. It contains other nodes (referenced loadpath.se files), and clusters (directories). Note that all the clusters in a loadpath.se file are direct children of the node. It means that, even if directories are arborescent this is not reflected in Liberty's universe.

To look for a supplier class, Liberty starts from its client. It tries to look for the "closest" class with the good name. It allows one to have many classes with the same name in the system. The algorithm is the following:

1. try to look for a class with the good name in a sub-cluster of the client. The less deep, the better.
2. try again, starting from the parent cluster of the client.
3. and so on, until the universe (the tree root) is reached.

If there is no client (e.g. a class given on the command line) the universe is searched and the class nearest to the root is selected.

If more than one class have the smallest distance, the compiler will bail because it cannot decide which to use. In the future, an extension to ACE files will allow someone to provide custom distances (a "distance" is the amount of depth to add from a cluster to a child; it defaults to 1)

For example:

/my/loadpath.se

./
internal/

This loadpath.se file represents a node with two children: the cluster in the directory of the loadpath.se file, and the cluster in the directory named "internal" in the former directory. Both have a distance equal to one, meaning that if there are two classes named FOO in both ./ and internal/ then the compiler will emit an error.

The tree will be the following:

 + <Universe>
    + "/my/loadpath.se"
    |  + /my/
    |  + /my/internal/
    + . . .
    |

loadpath.se files

Those files contain directories (clusters: the leaves of the "universe" tree) and references to other loadpath.se files (nodes of the "universe" tree).

Those path names may be written using - either a POSIX notation - or your local system notation

Note that for a library to be portable, you should prefer the POSIX notation.

Internals

Here are the gory details on how the "universe" tree is managed:

The tree itself is a bunch of classes situated in the smarteiffel/tools/ace cluster. It is a Composite which abstract class is CLASSES; most of the parent-children handling is done by concrete features in the CLUSTERS class.

                            *
             .---  CLASSES  <--.
             |         ^       | children
      parent |         |       |
             `-->  CLUSTERS ---'
              0-1      ^
                       |
            +----------+-------------+
            |          |             |
ACE --> UNIVERSE   LOADPATH   CLASSES_TREE --> CLUSTER
       (singleton)

• LOADPATH is a node of the tree. It references a loadpath.se file
• UNIVERSE is a singleton object held by ACE
• CLASSES_TREE is a leaf of the tree. It is a facade to the old CLUSTER class
• CLASSES_TREE_FACTORY is used to create a node or a leaf depending on whether the given path is a directory or a plain file. It creates CLASSES objects
• CLUSTER holds references to the known and loaded classes in that cluster
• ACE stays the Universe facade for the remaining of the Liberty system and dispatches request to the CLASSES tree (via the UNIVERSE)