From fd519748e9c828e03468dc61b331115f07b3fadd Mon Sep 17 00:00:00 2001
From: "Justin Clark-Casey (justincc)" <jjustincc@googlemail.com>
Date: Wed, 14 Aug 2013 19:35:02 +0100
Subject: [PATCH] Add method doc to Scene.RemoveClient() to ask any callers to
 use Scene.IncomingCloseAgent() instead.

IncomingCloseAgent() now sets the scene presence state machine properly, which is necessary to avoid races between multiple sources of close.
Hence, it's also necessary for everyone to consistently call IncomingCloseAgent()
Calling RemoveClient() directly is currently generating an attention-grabbing exception though this right now this is harmless.
---
 OpenSim/Region/Framework/Scenes/Scene.cs     | 12 ++++++++++++
 OpenSim/Region/Framework/Scenes/SceneBase.cs | 13 +++++++++++++
 2 files changed, 25 insertions(+)

diff --git a/OpenSim/Region/Framework/Scenes/Scene.cs b/OpenSim/Region/Framework/Scenes/Scene.cs
index a3bd388abc..d187377488 100644
--- a/OpenSim/Region/Framework/Scenes/Scene.cs
+++ b/OpenSim/Region/Framework/Scenes/Scene.cs
@@ -3382,6 +3382,18 @@ namespace OpenSim.Region.Framework.Scenes
             }
         }
 
+        /// <summary>
+        /// Remove the given client from the scene. 
+        /// </summary>
+        /// <remarks>
+        /// Only clientstack code should call this directly.  All other code should call IncomingCloseAgent() instead
+        /// to properly operate the state machine and avoid race conditions with other close requests (such as directly
+        /// from viewers).
+        /// </remarks>
+        /// <param name='agentID'>ID of agent to close</param>
+        /// <param name='closeChildAgents'>
+        /// Close the neighbour child agents associated with this client.
+        /// </param>
         public override void RemoveClient(UUID agentID, bool closeChildAgents)
         {
             AgentCircuitData acd = m_authenticateHandler.GetAgentCircuitData(agentID);
diff --git a/OpenSim/Region/Framework/Scenes/SceneBase.cs b/OpenSim/Region/Framework/Scenes/SceneBase.cs
index d2097ea7ad..5252b9638a 100644
--- a/OpenSim/Region/Framework/Scenes/SceneBase.cs
+++ b/OpenSim/Region/Framework/Scenes/SceneBase.cs
@@ -217,6 +217,19 @@ namespace OpenSim.Region.Framework.Scenes
         #region Add/Remove Agent/Avatar
 
         public abstract ISceneAgent AddNewClient(IClientAPI client, PresenceType type);
+
+        /// <summary>
+        /// Remove the given client from the scene. 
+        /// </summary>
+        /// <remarks>
+        /// Only clientstack code should call this directly.  All other code should call IncomingCloseAgent() instead
+        /// to properly operate the state machine and avoid race conditions with other close requests (such as directly
+        /// from viewers).
+        /// </remarks>
+        /// <param name='agentID'>ID of agent to close</param>
+        /// <param name='closeChildAgents'>
+        /// Close the neighbour child agents associated with this client.
+        /// </param>
         public abstract void RemoveClient(UUID agentID, bool closeChildAgents);
 
         public bool TryGetScenePresence(UUID agentID, out object scenePresence)