(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)?

I'm personally a fan of Addins, having seen them used in gnome-do. The fact that you get integrated online repository support is really handy, and something we'll need if we want to get people into making modules out of tree that can be easily added to OpenSim. --SeanDague 21:56, 28 January 2009 (UTC)

• 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)