(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 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
• The Scenes are instantiated.
  • For every ISharedRegionModule, one instance is created and Initialise is called.
  • For every ISharedRegionModule instance, PostInitialise is called.
  • For every Scene, for every INonSharedRegionModule, a new instance is created and Initialise called.
  • For every Scene, for every INonSharedRegionModule and ISharedRegionModule, AddRegion(scene) is called. The modules are associated to the Scene (for deletion on remove)

Adding a region

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

Removing a region

• For every INonSharedRegionModule of the scene and every ISharedRegionModule, RemoveRegion(scene) is called
• For every INonSharedRegionModule of the scene, 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

For simplicity, I'd like to do this as a "Removing a region", followed by a "Adding a region". Is there a functional reason for not doing that?

what happens to avatars that are in a region that you want to restart then? are they kicked out first? should they stay? --- DrScofield 09:51, 26 January 2009 (UTC)

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. Possible book-keeping references are removed; the ISharedRegionModule could now be garbage-collected.

Questions

• Loading via Mono.Addins? Via ExtensionLoader? Via our own loader (like the current one)?
• 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)