From f78cedd0e1d799aaec1562bcb1d1677c72bb5536 Mon Sep 17 00:00:00 2001
From: Dean Herbert <pe@ppy.sh>
Date: Mon, 28 Jun 2021 16:14:14 +0900
Subject: [PATCH] Reorder methods and add xmldoc for `BlockAllOperations`

---
 osu.Game/Database/RealmContextFactory.cs | 65 ++++++++++++++----------
 1 file changed, 37 insertions(+), 28 deletions(-)

diff --git a/osu.Game/Database/RealmContextFactory.cs b/osu.Game/Database/RealmContextFactory.cs
index 0b0263a16b..6214f4ca81 100644
--- a/osu.Game/Database/RealmContextFactory.cs
+++ b/osu.Game/Database/RealmContextFactory.cs
@@ -76,10 +76,26 @@ namespace osu.Game.Database
             return new RealmWriteUsage(createContext(), writeComplete);
         }
 
-        private void writeComplete()
+        /// <summary>
+        /// Flush any active contexts and block any further writes.
+        /// </summary>
+        /// <remarks>
+        /// This should be used in places we need to ensure no ongoing reads/writes are occurring with realm.
+        /// ie. to move the realm backing file to a new location.
+        /// </remarks>
+        /// <returns>An <see cref="IDisposable"/> which should be disposed to end the blocking section.</returns>
+        /// <exception cref="InvalidOperationException">Thrown if this context is already disposed.</exception>
+        public IDisposable BlockAllOperations()
         {
-            Monitor.Exit(writeLock);
-            pending_writes.Value--;
+            if (IsDisposed)
+                throw new InvalidOperationException(@"Attempted to block operations after already disposed.");
+
+            blockingLock.Wait();
+            flushContexts();
+
+            return new InvokeOnDisposal<RealmContextFactory>(this, endBlockingSection);
+
+            static void endBlockingSection(RealmContextFactory factory) => factory.blockingLock.Release();
         }
 
         protected override void Update()
@@ -113,6 +129,12 @@ namespace osu.Game.Database
             }
         }
 
+        private void writeComplete()
+        {
+            Monitor.Exit(writeLock);
+            pending_writes.Value--;
+        }
+
         private void onMigration(Migration migration, ulong lastSchemaVersion)
         {
             switch (lastSchemaVersion)
@@ -124,31 +146,6 @@ namespace osu.Game.Database
             }
         }
 
-        protected override void Dispose(bool isDisposing)
-        {
-            if (!IsDisposed)
-            {
-                // intentionally block all operations indefinitely. this ensures that nothing can start consuming a new context after disposal.
-                BlockAllOperations();
-                blockingLock?.Dispose();
-            }
-
-            base.Dispose(isDisposing);
-        }
-
-        public IDisposable BlockAllOperations()
-        {
-            if (IsDisposed)
-                throw new InvalidOperationException(@"Attempted to block operations after already disposed.");
-
-            blockingLock.Wait();
-            flushContexts();
-
-            return new InvokeOnDisposal<RealmContextFactory>(this, endBlockingSection);
-
-            static void endBlockingSection(RealmContextFactory factory) => factory.blockingLock.Release();
-        }
-
         private void flushContexts()
         {
             var previousContext = context;
@@ -161,6 +158,18 @@ namespace osu.Game.Database
             previousContext?.Dispose();
         }
 
+        protected override void Dispose(bool isDisposing)
+        {
+            if (!IsDisposed)
+            {
+                // intentionally block all operations indefinitely. this ensures that nothing can start consuming a new context after disposal.
+                BlockAllOperations();
+                blockingLock?.Dispose();
+            }
+
+            base.Dispose(isDisposing);
+        }
+
         /// <summary>
         /// A usage of realm from an arbitrary thread.
         /// </summary>