Revision as of 10:37, 13 May 2009

(This is a first draft-version and can change at any time until complete implementation. Feel free to comment, either on the Discussion page or on the opensim-dev mailing list)

Why

The current RegionModule system's API is in part inconsistent and doesn't really support region-restarts and adding/removing regions on the fly during a region-server run. E.g., the API says Initialise is called for every region (in every region-module), after that, PostInitialise is called for every region-module. When a new region is added, what should happen?

• Don't call Initialise: Then the region-module isn't initialised for that region, which leads to missing functionality.
• Call Initialise: Then PostInitialise was called too early. Actually, PostInitialise can not be called at all, because you can add a region after that anytime.

What should happen if a region is restarted? What should happen if a region is removed?

What

The new region-module system is based on three interfaces: ISharedRegionModule, INonSharedRegionModule and IRegionModuleBase, which is the base interface for the other two.

 public interface IRegionModuleBase
 {
     string Name { get; }
     void Initialise(IConfigSource source);
     void Close();
     void AddRegion(Scene scene);
     void RegionLoaded(Scene scene);
     void RemoveRegion(Scene scene);
 }

 public interface ISharedRegionModule : IRegionModuleBase
 {
     void PostInitialise();
 }

 public interface INonSharedRegionModule : IRegionModuleBase
 {
 }

• Loading the region-modules' classes happens via Mono.Addins on server-start.
• Instantiating the region-modules happens...
  • for ISharedRegionModules once after loading (on server start)
  • for INonSharedRegionModules after creation of the Scene object.
• You can cleanup when a region is removed.
• You can cleanup before the server shuts down.

Note

A PostInitialise for a INonSharedRegionModule doesn't make a lot of sense, as we don't have a certain point from which on we won't call Initialise on a INonSharedRegionModule again. Every time a new region is added (on restart, too), a new instance is created and Initialise is called on that instance, so the intended semantics of PostInitialise will never apply.

Details

Start of region-server

• Region-server starts, the classes of all region-modules are loaded in no particular order
  • For every ISharedRegionModule, one instance is created and Initialise is called.
  • For every ISharedRegionModule instance, PostInitialise is called.
• The Scenes are instantiated, one by one:
  • For every Scene
    • for every INonSharedRegionModule, a new instance is created and Initialise called.
    • for every INonSharedRegionModule and ISharedRegionModule, AddRegion(scene) is called. The modules are associated to the Scene (for deletion on remove)
    • for every INonSharedRegionModule and ISharedRegionModule, RegionLoaded(scene) is called (you can access the methods in other modules of that scene via scene.RequestModuleInterface<ModuleInterfaceType>() here).

Adding a region

• for every INonSharedRegionModule, a new instance is created and Initialise called.
• for every INonSharedRegionModule and ISharedRegionModule, AddRegion(scene) is called. The modules are associated to the Scene (for deletion on remove)
• for every INonSharedRegionModule and ISharedRegionModule, RegionLoaded(scene) is called.

Removing a region

• For every INonSharedRegionModule of the scene and every ISharedRegionModule, RemoveRegion(scene) is called
  • For the INonSharedRegionModules, Close is called
• Every module reference of the scene is removed from the scene. No references should be left after that; the INonSharedRegionModules could be garbage collected now.

Restarting a region

Restarting happens as a sequence of "Removing a region", followed by a "Adding a region". As usual, avatars that are in that region when it restarts are kicked.

Shutdown of the region-server

• For every scene, perform the "Removing a region" step:
  • RemoveRegion is called for all scenes and modules, Close is called for all the INonSharedRegionModules
• Close is called for all the ISharedRegionModule. The ISharedRegionModule could now be garbage-collected.

Notes

• RemoveRegion/Close is for cleaning up. Things you added in Initialise/AddRegion should be removed in Close/RemoveRegion again, respectively.
• The modules are loaded via Mono.Addins. This means, you can build your own assemblies with region modules, and by putting them into the <opensim>/bin folder, they will be loaded automatically. For this to work, you need to add a <something>.addin.xml file within your assembly-resources and provide a (or several) /OpenSim/RegionModule extensions in it. For examples, have a look at <opensim>/OpenSim/Region/CoreModules/Resources/CoreModulePlugin.addin.xml (and <opensim>/bin/OpenSim.addin.xml as the provider of the extension-point).

clear enough? Or should we add a spelled out example? HomerHorwitz 18:21, 12 May 2009 (UTC)

TODOs

• Configuration about which modules should be loaded.

we already have the enabled = true/false OpenSim.ini config option for most region modules --- DrScofield 09:53, 26 January 2009 (UTC)

which is a horribly ad hoc solution - we really do need a better way of controlling this imho --- Justincc 20:26, 28 January 2009 (UTC)

agree with Justin. A module shouldn't be responsible for turning itself off, it should never get loaded in the first place --SeanDague 21:51, 28 January 2009 (UTC)