Core abstractions

Core Controllers abstract classes

The LockedController

class licorn.core.classes.LockedController(*args, **kwargs)

Thread-safe object, protected by a global RLock, with a licornd property giving access to the Licorn® daemon (to benefit from the service* facility).

The __getitem__(), __setitem__(), and __delitem__() methods automatically aquire and release the global lock.

Note

the lock attribute is really a method returning the RLock object, because the lock object itself is not stored inside the instance: as Pyro can’t pickle a RLock object, it must be stored in the LockManager and looked up everytime, until we found a better solution.

New in version 1.3.

acquire()

acquire the controller global lock.

is_locked()

Return True if current controller lock is acquired, else False.

Warning

calling this is_locked() method costs a few CPU cycles, because of the object lookup (see note above). Try to avoid using it as much as possible.

licornd

release()

release the controller global lock.

The CoreController

class licorn.core.classes.CoreController(*args, **kwargs)

The CoreController class implements multiple functionnalities:

• storage for CoreUnitObject s, via the dict part of MixedDictObject.
• backends and extensions resolution via the generic method load_modules(). Backend priorities are handled if supported by the backends themselves (some do, and some don’t).
• reverse mappings via one or more protected dictionnary, created and updated on the fly.

Warning

updating CoreUnitObject s attributes directly doesn’t update the reverse mappings yet. This may be implemented in a future release. The reverse mapping functionnality may thus be considered incomplete, because a part of the update process must be done manually. Sorry for that, folks.

New in version 1.3.

dump()

Dump the internal data structures (debug and development use).

find_prefered_backend()

iterate through active backends and find the prefered one. We use a copy, in case there is no prefered yet: LMC.backends will change and this would crash the for_loop.

Note

TODO: this method may soon move into the BackendsManager instead of the controller.

load_extensions()

special case for SystemController.

reload()

load extensions if possible. This could not be possible if the controller is reload() ing during the CLIENT-daemon first launch of its method init_client_first_pass().

reload_extensions()

load all our extensions.

The CoreFSController

class licorn.core.classes.CoreFSController(*args, **kwargs)

FIXME: TO BE DOCUMENTED

New in version 1.3.

load_rules(core_obj, rules_path, object_info, vars_to_replace=None)

load special rules (rules defined by user) and merge system rules with them. Only the system default rule can be overwriten by the user default rule. If any other user rule is in conflict with a system rule, the system one will be used.

This function return only applicable rules

load_system_rules(vars_to_replace)

load system rules

parse_rules(rules_path, vars_to_replace, object_info, system_wide=True)

parse a rule from a line to a fsapi.FsapiObject. Returns a single Enumeration, containing either ONE ‘~’ rule, or a bunch of rules.

reload()

reload the templates rules generated from systems rules.

Core Objects abstract classes

The CoreUnitObject

class licorn.core.classes.CoreUnitObject(*args, **kwargs)

Common attributes for unit objects and modules in Licorn® core.

This class defines the following attributes:

oid

this attribute is the Licorn® object internal unique number (it’s unique among all instances of a given class). If not given in __init__(), it will be determined from next free oid stored in the CoreUnitObject.counter class attribute.

controller

a reference to the object’s container (manager or controller). Must be passed as __init__() argument, else the object won’t be able to easily find it’s parent when it needs it.

New in version 1.3.

controller

licornd

The CoreStoredObject

class licorn.core.classes.CoreStoredObject(*args, **kwargs)

Common attributes for stored objects (users, groups...). Add individual locking capability (better fine grained than global controller lock when possible), and the backend name of the current object storage.

New in version 1.2.

backend

is_ro_locked()

is_rw_locked()

lock

weakref

Modules abstract classes

Modules states

The ModulesManager

It’s the base for backends and extensions, because their principles are the same.

class licorn.core.classes.ModulesManager(*args, **kwargs)

The basics of a module manager. Backends and extensions are just particular cases of this class.

Note

TODO: implement module_sym_path auto-detection, for the day we will use it. For now we don’t care about it.

New in version 1.3.

by_id(name)

by_key(name)

the generic way, called from RWI.select()

by_name(name)

check(batch=False, auto_answer=None)

Check all enabled modules, then all available modules. Checking them will make them configure themselves, configure the required underlying system daemons, services or files, and eventually start services (depending of which type of module it is).

For more details, refer to the check() method of the desired module.

disable_func(module_name)

Try to disable a given module. What is exactly done is left to the module itself, because the current method will just call the disable() method of the module.

disable_module(module_name)

Try to disable a given module. What is exactly done is left to the module itself, because the current method will just call the disable() method of the module.

enable_func(module_name)

Try to enable a given module_name. What is exactly done is left to the module itself, because the current method will just call the enable() method of the module.

enable_module(module_name)

Try to enable a given module_name. What is exactly done is left to the module itself, because the current method will just call the enable() method of the module.

find_compatibles(controller)

Return a list of modules (real instances, not just names) compatible with a given controller.

Parameters:controller – the controller for which we want to lookup compatible extensions, passed as intance reference (not just the name, please).

guess_one(module_name)

load(server_side_modules=None)

load our modules (can be different type but the principle is the always the same).

If we are on the server, activate every module we can. If we are on a client, activate module only if module is enable on the server.

Note

TODO: implement module dependancies resolution. this is needed for the upcoming rdiff-backup/volumes extensions couple (at least).

object_id_str

object_type_str

sort_key

class licorn.core.classes.CoreModule(*args, **kwargs)

CoreModule is the base class for backends and extensions. It provides the generate_exception() method, called by controllers when a high-level problem occurs (for example, a conflict between duplicate-data coming from different backends; this is the typical problem a backend can’t detect).

A module class defines these class attributes:

• modules_depends: a list of modules instance names (not class) which must be available before the current one gets enabled.
• modules_conflicts: other modules instance names which conflict with the current one.

It must also define these instance attributes:

• controllers_compat: a list of controller names which will get data (methods or contents) from the current module.

Note

[work in progress] if self.controllers_compat contains system (name of SystemController global instance), the current class must implement the special system_load() method. This method will be called after module load and after SystemController instanciation, to reconnect the module data to its controller.

This is mainly because extensions are loaded after the SystemController instanciation in LMC, and we currently can’t do it differently, system needs to be up very early in the inter-daemon connection process.

New in version 1.2.

available = None

FIXME: better comment

check(batch=False, auto_answer=None)

default check method.

configuration = None

Internal configuration and data, loaded as objects.

controllers_compat = None

FIXME: better comment

disable()

In this abstract method, just return True (an abstract module is always disabled).

It’s up to derivatives to overload this method to implement whatever they need.

Note

your own module’s disable() method has to return True if the disable process succeeds, otherwise False.

enable()

In this abstract method, just return False (an abstract module can’t be enabled in any way).

It’s up to derivatives to overload this method to implement whatever they need.

Note

your own module’s enable() method has to return True if the enable process succeeds, otherwise False.

enabled = None

FIXME: better comment

event(event_name)

events = None

A collection of Event used to synchronize my threads.

generate_exception(extype, *args, **kwargs)

Generic mechanism for Exception dynamic generation.

Every module (backend or extension) can implement only the exceptions it handles, by defining special methods whose names start with genex_.

Parameters:

• extype –

  the type of the extension (most generally an Exception class name, passed as a string). This parameter will be used to resolve the wanted genex_extype() method, with Python’s builtin function getattr() on self.

  The existence of the wanted genex_* method is checked only at debbuging time with assert(). At normal runtime, a non existing method will make the program crash. You’re warned.

• args –
• kwargs – arguments that will be blindly passed to the genex_* methods.

initialize()

For an abstract module, this method always return False. For a standard module, it must return the attribute self.available, after having determined if the module is available or not.

Conditions of availability vary from a module to another. Generally speaking, a service-helper module should gather its service main configuration file and main binary, to check if they are installed.

• if not installed, just return self.available (it’s assigned False in self.__init__() and if you didn’t change it, it’s ready.
• if installed, change self.available value to True and return it, too.

Note

For more specific details, see classes LicornExtension and derivatives, and CoreBackend and derivatives, because there are other things to take in consideration when implementing end-of-road modules.

is_enabled()

In standard operations, this method checks if the module can be enabled (in particular conditions). but the abstract method of the base class just return self.available:

• for modules which don’t make a difference between available and enabled, this is perfect.
• for module which can enable/disable a system service (thus inherit from ServiceExtension, they must overload this method and provide the good implementation.

load_defaults()

A real backend will setup its own needed attributes with values strictly needed to work. This is done in case these values are not present in configuration files.

Any configuration file containing these values, will be loaded afterwards and will overwrite these attributes.

lock(lock_name)

locks = None

a collection of RLocks for multi-thread safety.

paths = None

Filenames of useful files, stored as strings.

peer_compat = None

A list of compatible modules. See Importing Modules for details

server_only = None

indicates that this module is meant to be used on server only (not replicated / configured on CLIENTS).

threads = None

Threads that will be collected by daemon to be started/stopped.