From d23550dea5bbd1214f469a2be0e18d6c1d4ef84b Mon Sep 17 00:00:00 2001
From: "Justin Clark-Casey (justincc)" <jjustincc@googlemail.com>
Date: Tue, 17 Apr 2012 23:54:51 +0100
Subject: [PATCH] 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 +++
 .../Framework/Scenes/SceneObjectGroup.cs      | 19 +++++++++++++++++++
 2 files changed, 22 insertions(+)

diff --git a/OpenSim/Region/Framework/Scenes/SceneGraph.cs b/OpenSim/Region/Framework/Scenes/SceneGraph.cs
index a15d62d813..335e9c511f 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 ce88a75f04..f6a759e7fc 100644
--- a/OpenSim/Region/Framework/Scenes/SceneObjectGroup.cs
+++ b/OpenSim/Region/Framework/Scenes/SceneObjectGroup.cs
@@ -1973,6 +1973,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)
         {
@@ -2056,6 +2060,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)
@@ -2067,6 +2076,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>
@@ -2092,6 +2106,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>