From a341819711cda358652ad84b1e507d9559ecabfd Mon Sep 17 00:00:00 2001
From: crupest <crupest@outlook.com>
Date: Tue, 27 Apr 2021 18:22:57 +0800
Subject: refactor: Refactor data services.

---
 BackEnd/Timeline/Services/Data/IDataManager.cs | 49 ++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)
 create mode 100644 BackEnd/Timeline/Services/Data/IDataManager.cs

(limited to 'BackEnd/Timeline/Services/Data/IDataManager.cs')

diff --git a/BackEnd/Timeline/Services/Data/IDataManager.cs b/BackEnd/Timeline/Services/Data/IDataManager.cs
new file mode 100644
index 00000000..6a87c1b2
--- /dev/null
+++ b/BackEnd/Timeline/Services/Data/IDataManager.cs
@@ -0,0 +1,49 @@
+using System;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace Timeline.Services.Data
+{
+    /// <summary>
+    /// A data manager controlling data.
+    /// </summary>
+    /// <remarks>
+    /// Identical data will be saved as one copy and return the same tag.
+    /// Every data has a ref count. When data is retained, ref count increase.
+    /// When data is freed, ref count decease. If ref count is decreased
+    /// to 0, the data entry will be destroyed and no longer occupy space.
+    /// </remarks>
+    public interface IDataManager
+    {
+        /// <summary>
+        /// Saves the data to a new entry if it does not exist, 
+        /// increases its ref count and returns a tag to the entry.
+        /// </summary>
+        /// <param name="data">The data. Can't be null.</param>
+        /// <param name="cancellationToken">Cancellation token.</param>
+        /// <returns>The tag of the created entry.</returns>
+        /// <exception cref="ArgumentNullException">Thrown when <paramref name="data"/> is null.</exception>
+        public Task<string> RetainEntry(byte[] data, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Decrease the the ref count of the entry.
+        /// Remove it if ref count is zero.
+        /// </summary>
+        /// <param name="tag">The tag of the entry.</param>
+        /// <param name="cancellationToken">Cancellation token.</param>
+        /// <exception cref="ArgumentNullException">Thrown when <paramref name="tag"/> is null.</exception>
+        /// <remarks>
+        /// It's no-op if entry with tag does not exist.
+        /// </remarks>
+        public Task FreeEntry(string tag, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Retrieve the entry with given tag. If not exist, returns null.
+        /// </summary>
+        /// <param name="tag">The tag of the entry.</param>
+        /// <param name="cancellationToken">Cancellation token.</param>
+        /// <returns>The data of the entry. If not exist, returns null.</returns>
+        /// <exception cref="ArgumentNullException">Thrown when <paramref name="tag"/> is null.</exception>
+        public Task<byte[]?> GetEntry(string tag, CancellationToken cancellationToken = default);
+    }
+}
-- 
cgit v1.2.3