From 859646ef5cf016eecfefb53b2b388fe880c39a3a Mon Sep 17 00:00:00 2001
From: Justin Clark-Casey (justincc)
Date: Tue, 17 Apr 2012 23:54:51 +0100
Subject: minor: Add some method doc.  Add warnings since calling SOG
 link/delink methods directly rather than through Scene may allow race
 conditions.

---
 OpenSim/Region/Framework/Scenes/SceneGraph.cs       |  3 +++
 OpenSim/Region/Framework/Scenes/SceneObjectGroup.cs | 19 +++++++++++++++++++
 2 files changed, 22 insertions(+)

(limited to 'OpenSim/Region')

diff --git a/OpenSim/Region/Framework/Scenes/SceneGraph.cs b/OpenSim/Region/Framework/Scenes/SceneGraph.cs
index 0098add..67eb0fe 100644
--- a/OpenSim/Region/Framework/Scenes/SceneGraph.cs
+++ b/OpenSim/Region/Framework/Scenes/SceneGraph.cs
@@ -91,6 +91,9 @@ namespace OpenSim.Region.Framework.Scenes
         /// </summary>
         protected internal Dictionary<uint, SceneObjectGroup> SceneObjectGroupsByLocalPartID = new Dictionary<uint, SceneObjectGroup>();        
 
+        /// <summary>
+        /// Lock to prevent object group update, linking and delinking operations from running concurrently.
+        /// </summary>
         private Object m_updateLock = new Object();
 
         #endregion
diff --git a/OpenSim/Region/Framework/Scenes/SceneObjectGroup.cs b/OpenSim/Region/Framework/Scenes/SceneObjectGroup.cs
index a49ed13..8e786c1 100644
--- a/OpenSim/Region/Framework/Scenes/SceneObjectGroup.cs
+++ b/OpenSim/Region/Framework/Scenes/SceneObjectGroup.cs
@@ -1962,6 +1962,10 @@ namespace OpenSim.Region.Framework.Scenes
         /// <summary>
         /// Link the prims in a given group to this group
         /// </summary>
+        /// <remarks>
+        /// Do not call this method directly - use Scene.LinkObjects() instead to avoid races between threads.
+        /// FIXME: There are places where scripts call these methods directly without locking.  This is a potential race condition.
+        /// </remarks>
         /// <param name="objectGroup">The group of prims which should be linked to this group</param>
         public void LinkToGroup(SceneObjectGroup objectGroup)
         {
@@ -2045,6 +2049,11 @@ namespace OpenSim.Region.Framework.Scenes
         /// Delink the given prim from this group.  The delinked prim is established as
         /// an independent SceneObjectGroup.
         /// </summary>
+        /// <remarks>
+        /// FIXME: This method should not be called directly since it bypasses update locking, allowing a potential race
+        /// condition.  But currently there is no
+        /// alternative method that does take a lonk to delink a single prim.
+        /// </remarks>
         /// <param name="partID"></param>
         /// <returns>The object group of the newly delinked prim.  Null if part could not be found</returns>
         public SceneObjectGroup DelinkFromGroup(uint partID)
@@ -2056,6 +2065,11 @@ namespace OpenSim.Region.Framework.Scenes
         /// Delink the given prim from this group.  The delinked prim is established as
         /// an independent SceneObjectGroup.
         /// </summary>
+        /// <remarks>
+        /// FIXME: This method should not be called directly since it bypasses update locking, allowing a potential race
+        /// condition.  But currently there is no
+        /// alternative method that does take a lonk to delink a single prim.
+        /// </remarks>
         /// <param name="partID"></param>
         /// <param name="sendEvents"></param>
         /// <returns>The object group of the newly delinked prim.  Null if part could not be found</returns>
@@ -2081,6 +2095,11 @@ namespace OpenSim.Region.Framework.Scenes
         /// Delink the given prim from this group.  The delinked prim is established as
         /// an independent SceneObjectGroup.
         /// </summary>
+        /// <remarks>
+        /// FIXME: This method should not be called directly since it bypasses update locking, allowing a potential race
+        /// condition.  But currently there is no
+        /// alternative method that does take a lonk to delink a single prim.
+        /// </remarks>
         /// <param name="partID"></param>
         /// <param name="sendEvents"></param>
         /// <returns>The object group of the newly delinked prim.</returns>
-- 
cgit v1.1