Improved usage consistency by changing Buffer.Open to protected

Author: justinstenning

Examples/ClientTest/Program.cs

@@ -44,8 +44,6 @@ static void Main(string[] args)
             Console.WriteLine("Open existing shared memory circular buffer");
             using (SharedMemory.CircularBuffer theClient = new SharedMemory.CircularBuffer("TEST"))
             {
-                theClient.Open();
-
                 Console.WriteLine("Buffer {0} opened, NodeBufferSize: {1}, NodeCount: {2}", theClient.Name, theClient.NodeBufferSize, theClient.NodeCount);
 
                 long bufferSize = theClient.NodeBufferSize;

Examples/ServerTest/Program.cs

@@ -60,10 +60,8 @@ static void Main(string[] args)
 
 
             Console.WriteLine("Create shared memory circular buffer");
-            using (var theServer = new SharedMemory.CircularBuffer("TEST", count, size, true))
+            using (var theServer = new SharedMemory.CircularBuffer("TEST", count, size))
             {
-                theServer.Open();
-
                 Console.WriteLine("Circular buffer producer created.");
                 Console.WriteLine("Ready for client...");
                 Thread.Sleep(1000);

Examples/SingleProcess/Program.cs

@@ -50,13 +50,7 @@ static void Main(string[] args)
 
             long bytesRead = 0;
 
-            var server = new SharedMemory.CircularBuffer("TEST", count, size, true);
-            if (!server.Open())
-            {
-                Console.WriteLine("Unable to allocate memory.");
-                Console.ReadLine();
-                return;
-            }
+            var server = new SharedMemory.CircularBuffer("TEST", count, size);
 
             Stopwatch sw = Stopwatch.StartNew();
 
@@ -65,7 +59,6 @@ static void Main(string[] args)
                 byte[] testData = new byte[size];
 
                 var client = new SharedMemory.CircularBuffer("TEST");
-                client.Open();
 
                 Stopwatch clientTime = new Stopwatch();
                 clientTime.Start();

SharedMemory/Array.cs

@@ -87,7 +87,7 @@ public Array(string name, int length)
         /// Opens an existing shared memory array with the name as specified by <paramref name="name"/>.
         /// </summary>
         /// <param name="name">The name of the shared memory array to open.</param>
-        /// <exception cref="ArgumentOutOfRangeException">If the shared memory location specified by <paramref name="name"/> does not have a <see cref="BufferSize"/> that is evenly divisable by the size of <typeparamref name="T"/>.</exception>
+        /// <exception cref="ArgumentOutOfRangeException">If the shared memory location specified by <paramref name="name"/> does not have a <see cref="Buffer.BufferSize"/> that is evenly divisable by the size of <typeparamref name="T"/>.</exception>
         public Array(string name)
             : base(name, 0, false)
         {
@@ -98,9 +98,12 @@ public Array(string name)
 
         #endregion
 
+        /// <summary>
+        /// Perform any initialisation required when opening the shared memory array
+        /// </summary>
+        /// <returns>true if successful</returns>
         protected override bool DoOpen()
         {
-
             if (!IsOwnerOfSharedMemory)
             {
                 if (BufferSize % _elementSize != 0)
@@ -131,7 +134,7 @@ public void Write(ref T data, int index)
         /// </summary>
         /// <param name="buffer">The source array to copy elements from.</param>
         /// <param name="startIndex">The zero-based index of the shared memory array element to begin writing to.</param>
-        /// <exception cref="IndexOutOfRangeException"><paramref name="startIndex"/> is less than 0 -or- <see cref="buffer.Length"/> + <paramref name="startIndex"/> is greater than <see cref="Length"/>.</exception>
+        /// <exception cref="IndexOutOfRangeException"><paramref name="startIndex"/> is less than 0 -or- length of <paramref name="buffer"/> + <paramref name="startIndex"/> is greater than <see cref="Length"/>.</exception>
         /// <exception cref="ArgumentNullException"><paramref name="buffer"/> must not be null</exception>
         public void Write(T[] buffer, int startIndex = 0)
         {
@@ -167,7 +170,7 @@ public void Read(out T data, int index)
         /// </summary>
         /// <param name="buffer">The destination array to copy the elements into.</param>
         /// <param name="startIndex">The zero-based index of the shared memory array element to begin reading from.</param>
-        /// <exception cref="IndexOutOfRangeException"><paramref name="startIndex"/> is less than 0 -or- <see cref="buffer.Length"/> + <paramref name="startIndex"/> is greater than <see cref="Length"/>.</exception>
+        /// <exception cref="IndexOutOfRangeException"><paramref name="startIndex"/> is less than 0 -or- length of <paramref name="buffer"/> + <paramref name="startIndex"/> is greater than <see cref="Length"/>.</exception>
         /// <exception cref="ArgumentNullException"><paramref name="buffer"/> must not be null</exception>
         public void CopyTo(T[] buffer, int startIndex = 0)
         {

SharedMemory/Buffer.cs

@@ -112,9 +112,21 @@ protected virtual long BufferOffset
 
         #region Protected field members
 
+        /// <summary>
+        /// Memory mapped file
+        /// </summary>
         protected MemoryMappedFile Mmf;
+        /// <summary>
+        /// Memory mapped view
+        /// </summary>
         protected MemoryMappedViewAccessor View;
+        /// <summary>
+        /// Pointer to the memory mapped view
+        /// </summary>
         protected byte* ViewPtr = null;
+        /// <summary>
+        /// Pointer to the header within shared memory
+        /// </summary>
         protected Header* Header = null;
 
         #endregion
@@ -158,6 +170,9 @@ protected Buffer(string name, long bufferSize, bool ownsSharedMemory)
             }
         }
 
+        /// <summary>
+        /// Destructor - for Dispose(false)
+        /// </summary>
         ~Buffer()
         {
             Dispose(false);
@@ -168,15 +183,17 @@ protected Buffer(string name, long bufferSize, bool ownsSharedMemory)
         #region Open / Close
 
         /// <summary>
-        /// Create a new or open an existing shared memory buffer with the name of <see cref="Name"/>. 
+        /// Creates a new or opens an existing shared memory buffer with the name of <see cref="Name"/> depending on the value of <see cref="IsOwnerOfSharedMemory"/>. 
         /// </summary>
         /// <returns>True if the memory was successfully mapped</returns>
         /// <remarks>If <see cref="IsOwnerOfSharedMemory"/> is true then the shared memory buffer will be created, opening will fail in this case if the shared memory already exists. Otherwise if IsOwnerOfSharedMemory is false then the shared memory buffer will be opened, which will fail if it doesn't already exist.</remarks>
         /// <exception cref="System.IO.IOException">If trying to create a new shared memory buffer with a duplicate name as buffer owner.</exception>
         /// <exception cref="System.IO.FileNotFoundException">If trying to open a new shared memory buffer that does not exist as a consumer of existing buffer.</exception>
         /// <exception cref="System.ArgumentOutOfRangeException">If trying to create a new shared memory buffer with a size larger than the logical addressable space.</exception>
-        public bool Open()
+        protected bool Open()
         {
+            Close();
+
             try
             {
                 // Attempts to create or open the shared memory with a name of this.Name
@@ -325,7 +342,7 @@ protected virtual void Write<T>(ref T data, long bufferPosition = 0)
         /// Writes an array of <typeparamref name="T"/> into the buffer
         /// </summary>
         /// <typeparam name="T">A structure type</typeparam>
-        /// <param name="data">An array of <typeparamref name="T"/> to be written. The length of this array controls the number of elements to be written.</param>
+        /// <param name="buffer">An array of <typeparamref name="T"/> to be written. The length of this array controls the number of elements to be written.</param>
         /// <param name="bufferPosition">The offset within the buffer region of the shared memory to write to.</param>
         protected virtual void Write<T>(T[] buffer, long bufferPosition = 0)
             where T : struct
@@ -374,7 +391,7 @@ protected virtual void Read<T>(out T data, long bufferPosition = 0)
         /// Reads an array of <typeparamref name="T"/> from the buffer
         /// </summary>
         /// <typeparam name="T">A structure type</typeparam>
-        /// <param name="data">Array that will contain the values read from the buffer. The length of this array controls the number of elements to read.</param>
+        /// <param name="buffer">Array that will contain the values read from the buffer. The length of this array controls the number of elements to read.</param>
         /// <param name="bufferPosition">The offset within the buffer region of the shared memory to read from.</param>
         protected virtual void Read<T>(T[] buffer, long bufferPosition = 0)
             where T : struct
@@ -407,11 +424,18 @@ protected virtual void Read(Action<IntPtr> readFunc, long bufferPosition = 0)
 
         #region IDisposable
 
+        /// <summary>
+        /// Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.
+        /// </summary>
         public void Dispose()
         {
             Dispose(true);
         }
 
+        /// <summary>
+        /// IDisposable pattern - dispose of managed/unmanaged resources
+        /// </summary>
+        /// <param name="disposeManagedResources">true to dispose of managed resources as well as unmanaged.</param>
         protected virtual void Dispose(bool disposeManagedResources)
         {
             if (disposeManagedResources)
@@ -425,7 +449,7 @@ protected virtual void Dispose(bool disposeManagedResources)
         #region Native Imports
 
         /// <summary>
-        /// Allow copying memory from one IntPtr to another. Required as the <see cref="Marshal.Copy"/> implementation does not provide an appropriate override.
+        /// Allow copying memory from one IntPtr to another. Required as the <see cref="System.Runtime.InteropServices.Marshal.Copy(System.IntPtr, System.IntPtr[], int, int)"/> implementation does not provide an appropriate override.
         /// </summary>
         /// <param name="dest"></param>
         /// <param name="src"></param>

SharedMemory/BufferReadWrite.cs

@@ -39,14 +39,25 @@ public unsafe class BufferReadWrite : BufferWithLocks
     {
         #region Constructors
 
-        public BufferReadWrite(string name, int bufferSize, bool ownsSharedMemory)
-            : base(name, bufferSize, ownsSharedMemory)
+        /// <summary>
+        /// Creates a new shared memory buffer with the specified name and size
+        /// </summary>
+        /// <param name="name">The name of the shared memory to create</param>
+        /// <param name="bufferSize">The size of the buffer</param>
+        public BufferReadWrite(string name, int bufferSize)
+            : base(name, bufferSize, true)
         {
+            Open();
         }
 
+        /// <summary>
+        /// Opens an existing shared memory buffer with the specified name
+        /// </summary>
+        /// <param name="name">The name of the shared memory to open</param>
         public BufferReadWrite(string name)
             : base(name, 0, false)
         {
+            Open();
         }
 
         #endregion
@@ -69,7 +80,7 @@ public BufferReadWrite(string name)
         /// Writes an array of <typeparamref name="T"/> into the buffer
         /// </summary>
         /// <typeparam name="T">A structure type</typeparam>
-        /// <param name="data">An array of <typeparamref name="T"/> to be written. The length of this array controls the number of elements to be written.</param>
+        /// <param name="buffer">An array of <typeparamref name="T"/> to be written. The length of this array controls the number of elements to be written.</param>
         /// <param name="bufferPosition">The offset within the buffer region of the shared memory to write to.</param>
         new public void Write<T>(T[] buffer, long bufferPosition = 0)
             where T : struct
@@ -118,7 +129,7 @@ public BufferReadWrite(string name)
         /// Reads an array of <typeparamref name="T"/> from the buffer
         /// </summary>
         /// <typeparam name="T">A structure type</typeparam>
-        /// <param name="data">Array that will contain the values read from the buffer. The length of this array controls the number of elements to read.</param>
+        /// <param name="buffer">Array that will contain the values read from the buffer. The length of this array controls the number of elements to read.</param>
         /// <param name="bufferPosition">The offset within the buffer region of the shared memory to read from.</param>
         new public void Read<T>(T[] buffer, long bufferPosition = 0)
             where T : struct

SharedMemory/BufferWithLocks.cs

@@ -36,7 +36,7 @@ namespace SharedMemory
     /// <summary>
     /// <para>Extends <see cref="Buffer"/> to support simple thread-synchronisation for read/write 
     /// to the buffer by allowing callers to acquire and release read/write locks.</para>
-    /// <para>All buffer read/write operations have been overloaded to first perform a <see cref="EventWaitHandle.WaitOne"/> 
+    /// <para>All buffer read/write operations have been overloaded to first perform a <see cref="System.Threading.WaitHandle.WaitOne()"/> 
     /// using the <see cref="ReadWaitEvent"/> and <see cref="WriteWaitEvent"/> respectively.</para>
     /// <para>By default all read/write operations will not block, it is necessary to first acquire locks 
     /// through calls to <see cref="AcquireReadLock"/> and <see cref="AcquireWriteLock"/> as appropriate, with corresponding 
@@ -74,7 +74,7 @@ protected BufferWithLocks(string name, long bufferSize, bool ownsSharedMemory)
         #region Synchronisation
 
         /// <summary>
-        /// Blocks the current thread until it is able to acquire a read lock. If succesfull all subsequent writes will be blocked until after a call to <paramref name="ReleaseReadLock"/>.
+        /// Blocks the current thread until it is able to acquire a read lock. If succesfull all subsequent writes will be blocked until after a call to <see cref="ReleaseReadLock"/>.
         /// </summary>
         /// <param name="millisecondsTimeout">The number of milliseconds to wait, or <see cref="System.Threading.Timeout.Infinite" /> (-1) to wait indefinitely.</param>
         /// <returns>true if the read lock was able to be acquired, otherwise false.</returns>
@@ -97,7 +97,7 @@ public void ReleaseReadLock()
         }
 
         /// <summary>
-        /// Blocks the current thread until it is able to acquire a write lock. If succesfull all subsequent reads will be blocked until after a call to <paramref name="ReleaseWriteLock"/>.
+        /// Blocks the current thread until it is able to acquire a write lock. If succesfull all subsequent reads will be blocked until after a call to <see cref="ReleaseWriteLock"/>.
         /// </summary>
         /// <param name="millisecondsTimeout">The number of milliseconds to wait, or System.Threading.Timeout.Infinite (-1) to wait indefinitely.</param>
         /// <returns>true if the write lock was able to be acquired, otherwise false.</returns>
@@ -139,7 +139,7 @@ protected override void Write<T>(ref T data, long bufferPosition = 0)
         /// Writes an array of <typeparamref name="T"/> into the buffer
         /// </summary>
         /// <typeparam name="T">A structure type</typeparam>
-        /// <param name="data">An array of <typeparamref name="T"/> to be written. The length of this array controls the number of elements to be written.</param>
+        /// <param name="buffer">An array of <typeparamref name="T"/> to be written. The length of this array controls the number of elements to be written.</param>
         /// <param name="bufferPosition">The offset within the buffer region of the shared memory to write to.</param>
         protected override void Write<T>(T[] buffer, long bufferPosition = 0)
         {
@@ -190,7 +190,7 @@ protected override void Read<T>(out T data, long bufferPosition = 0)
         /// Reads an array of <typeparamref name="T"/> from the buffer
         /// </summary>
         /// <typeparam name="T">A structure type</typeparam>
-        /// <param name="data">Array that will contain the values read from the buffer. The length of this array controls the number of elements to read.</param>
+        /// <param name="buffer">Array that will contain the values read from the buffer. The length of this array controls the number of elements to read.</param>
         /// <param name="bufferPosition">The offset within the buffer region of the shared memory to read from.</param>
         protected override void Read<T>(T[] buffer, long bufferPosition = 0)
         {
@@ -225,6 +225,10 @@ protected override void Read(Action<IntPtr> readFunc, long bufferPosition = 0)
 
         #region IDisposable
 
+        /// <summary>
+        /// IDisposable pattern
+        /// </summary>
+        /// <param name="disposeManagedResources">true to release managed resources</param>
         protected override void Dispose(bool disposeManagedResources)
         {
             if (disposeManagedResources)