Commits

rimmington  committed f30effd Draft

documentation & line length fixes

  • Participants
  • Parent commits 0c7ca3e

Comments (0)

Files changed (18)

File Cineraria.Concurrency/Barrier.cs

         /// <summary>
         /// Object used for lock() blocks.
         /// </summary>
-        /// <remarks>See http://stackoverflow.com/questions/251391/why-is-lockthis-bad </remarks>
         private readonly object _syncRoot = new object();
 
         /// <summary>
         private bool _isBroken = false;
 
         /// <summary>
-        /// Whether this barrier is open, ie. threshold was met and threads can leave.
+        /// Whether this barrier is open, ie. threshold was met and threads can
+        /// leave.
         /// </summary>
         private bool _isOpen = false;
 
         /// <summary>
         /// Initializes a new instance of the <see cref="Barrier"/> class.
         /// </summary>
-        /// <param name="threshold">The number of threads that must arrive for the barrier to open.</param>
-        /// <exception cref="ArgumentOutOfRangeException"><paramref name="threshold"/> must be greater than zero.</exception>
+        /// <param name="threshold">
+        /// The number of threads that must arrive for the barrier to open.
+        /// </param>
+        /// <exception cref="ArgumentOutOfRangeException">
+        /// <paramref name="threshold"/> must be greater than zero.
+        /// </exception>
         public Barrier(int threshold)
         {
             if (threshold < 1)
         }
 
         /// <summary>
-        /// Gets the number of threads that must arrive for the barrier to open.
+        /// Gets the number of threads that must arrive for the barrier to
+        /// open.
         /// </summary>
         public int Threshold
         {
                 }
             }
 
-            bool acquiredGoPermission = this._goPermission.Attempt(
+            bool acquiredGoPermission = this._goPermission.Acquire(
                 milliseconds);
 
             lock (this._syncRoot)

File Cineraria.Concurrency/BorkBuffer.cs

         /// <summary>
         /// Object used for lock() blocks.
         /// </summary>
-        /// <remarks>See http://stackoverflow.com/questions/251391/why-is-lockthis-bad </remarks>
         private readonly object _syncRoot = new object();
 
         /// <summary>
-        /// Initializes a new instance of the <see cref="BorkBuffer&lt;T&gt;"/> class.
+        /// Initializes a new instance of the
+        /// <see cref="BorkBuffer&lt;T&gt;"/> class.
         /// </summary>
         public BorkBuffer()
         {

File Cineraria.Concurrency/BoundedChannel.cs

 // -----------------------------------------------------------------------
 namespace Cineraria.Concurrency
 {
-    using ThreadInterruptedException = System.Threading.ThreadInterruptedException;
+    using ThreadInterruptedException =
+        System.Threading.ThreadInterruptedException;
 
     /// <summary>
     /// A thread-safe channel with a capacity limit.
         private readonly Semaphore _putPermission;
 
         /// <summary>
-        /// Initializes a new instance of the <see cref="BoundedChannel&lt;T&gt;"/> class.
+        /// Initializes a new instance of the
+        /// <see cref="BoundedChannel&lt;T&gt;"/> class.
         /// </summary>
         /// <param name="limit">The capacity limit.</param>
         public BoundedChannel(int limit)
         }
 
         /// <summary>
-        /// Puts the specified item into the channel. If the channel is full, waits a maximum of
-        /// <paramref name="milliseconds"/> before giving up.
+        /// Puts the specified item into the channel. If the channel is full,
+        /// waits a maximum of <paramref name="milliseconds"/> before giving up.
         /// </summary>
         /// <param name="item">The item.</param>
-        /// <param name="milliseconds">The maximum number of milliseconds to wait before giving up.</param>
-        /// <returns>true if the specified item was put in the buffer, false otherwise.</returns>
+        /// <param name="milliseconds">
+        /// The maximum number of milliseconds to wait before giving up.
+        /// </param>
+        /// <returns>
+        /// true if the specified item was put in the buffer, false otherwise.
+        /// </returns>
         public override bool Offer(T item, int milliseconds)
         {
-            if (this._putPermission.Attempt(milliseconds))
+            if (this._putPermission.Acquire(milliseconds))
             {
                 try
                 {
         /// <paramref name="milliseconds"/> before giving up.
         /// </summary>
         /// <param name="item">The item taken.</param>
-        /// <param name="milliseconds">The maximum number of milliseconds to wait before giving up.</param>
+        /// <param name="milliseconds">
+        /// The maximum number of milliseconds to wait before giving up.
+        /// </param>
         /// <returns>true if a item was taken, false otherwise.</returns>
         public override bool Poll(out T item, int milliseconds)
         {

File Cineraria.Concurrency/BrokenBarrierException.cs

         /// The <see cref="StreamingContext"/> that contains contextual
         /// information about the source or destination.
         /// </param>
-        protected BrokenBarrierException(SerializationInfo info, StreamingContext context)
+        protected BrokenBarrierException(
+            SerializationInfo info,
+            StreamingContext context)
             : base(info, context)
         {
         }

File Cineraria.Concurrency/BusyWaitBuffer.cs

         /// <summary>
         /// Object used for lock() blocks.
         /// </summary>
-        /// <remarks>See http://stackoverflow.com/questions/251391/why-is-lockthis-bad </remarks>
         private readonly object _syncRoot = new object();
 
         /// <summary>
-        /// Initializes a new instance of the <see cref="BusyWaitBuffer&lt;T&gt;"/> class.
+        /// Initializes a new instance of the
+        /// <see cref="BusyWaitBuffer&lt;T&gt;"/> class.
         /// </summary>
         public BusyWaitBuffer()
         {

File Cineraria.Concurrency/Channel.cs

     using System;
     using System.Collections;
     using System.Collections.Generic;
-    using ThreadInterruptedException = System.Threading.ThreadInterruptedException;
+    using ThreadInterruptedException =
+        System.Threading.ThreadInterruptedException;
 
     /// <summary>
     /// A thread-safe generic channel.
         /// <summary>
         /// Object used for lock() blocks.
         /// </summary>
-        /// <remarks>
-        /// See http://stackoverflow.com/questions/251391/why-is-lockthis-bad
-        /// </remarks>
         private readonly object _syncRoot = new object();
 
         /// <summary>
         /// <returns>true if a item was taken, false otherwise.</returns>
         public virtual bool Poll(out T item, int milliseconds)
         {
-            if (this._takePermission.Attempt(milliseconds))
+            if (this._takePermission.Acquire(milliseconds))
             {
                 try
                 {

File Cineraria.Concurrency/FifoSemaphore.cs

         private readonly object _syncRoot = new object();
 
         /// <summary>
-        /// A queue of semaphores, one for each thread waiting on this <see cref="FifoSemaphore"/>.
+        /// A queue of semaphores, one for each thread waiting on this
+        /// <see cref="FifoSemaphore"/>.
         /// </summary>
         private readonly Queue<Semaphore> _queue = new Queue<Semaphore>();
 
         private int _tokens = 0;
 
         /// <summary>
-        /// Initializes a new instance of the <see cref="FifoSemaphore"/> class with 0 logical tokens.
+        /// Initializes a new instance of the <see cref="FifoSemaphore"/> class
+        /// with 0 logical tokens.
         /// </summary>
         public FifoSemaphore()
             : this(0)
         }
 
         /// <summary>
-        /// Initializes a new instance of the <see cref="FifoSemaphore"/> class with the specified
+        /// Initializes a new instance of the <see cref="FifoSemaphore"/> class
+        /// with the specified
         /// number of logical tokens.
         /// </summary>
         /// <param name="tokens">The tokens.</param>
         /// <summary>
         /// Releases the specified number of logical tokens.
         /// </summary>
-        /// <param name="tokens">The number of logical tokens to release.</param>
+        /// <param name="tokens">
+        /// The number of logical tokens to release.
+        /// </param>
         public void Release(int tokens)
         {
             if (tokens <= 0)

File Cineraria.Concurrency/GuardedBuffer.cs

         /// <summary>
         /// Object used for lock() blocks.
         /// </summary>
-        /// <remarks>See http://stackoverflow.com/questions/251391/why-is-lockthis-bad </remarks>
         private readonly object _syncRoot = new object();
 
         /// <summary>
-        /// Initializes a new instance of the <see cref="GuardedBuffer&lt;T&gt;"/> class.
+        /// Initializes a new instance of the
+        /// <see cref="GuardedBuffer&lt;T&gt;"/> class.
         /// </summary>
         public GuardedBuffer()
         {
         }
 
         /// <summary>
-        /// Takes an item from the buffer. If empty, waits/sleeps until it is not.
+        /// Takes an item from the buffer. If empty, waits until it is not.
         /// </summary>
         /// <returns>The item.</returns>
         public T Take()

File Cineraria.Concurrency/Mutex.cs

     public class Mutex : Semaphore
     {
         /// <summary>
-        /// Initializes a new instance of the <see cref="Mutex"/> class with 1 logical tokens.
+        /// Initializes a new instance of the <see cref="Mutex"/> class with 1
+        /// logical token.
         /// </summary>
         public Mutex()
             : this(1)
         }
 
         /// <summary>
-        /// Initializes a new instance of the <see cref="Mutex"/> class with the specified number
-        /// of logical tokens.
+        /// Initializes a new instance of the <see cref="Mutex"/> class with
+        /// the specified number of logical tokens.
         /// </summary>
-        /// <param name="tokens">The number of logical tokens to start with.</param>
-        /// <exception cref="ArgumentOutOfRangeException"><paramref name="tokens"/> must be 0 or 1.</exception>
+        /// <param name="tokens">
+        /// The number of logical tokens to start with.
+        /// </param>
+        /// <exception cref="ArgumentOutOfRangeException">
+        /// <paramref name="tokens"/> must be 0 or 1.
+        /// </exception>
         public Mutex(int tokens)
             : base(tokens)
         {
         /// <summary>
         /// Releases the specified number of logical tokens.
         /// </summary>
-        /// <param name="tokens">The number of logical tokens to release.</param>
-        /// <exception cref="ArgumentOutOfRangeException">tokens must be 1.</exception>
-        /// <exception cref="InvalidOperationException">Cannot release a mutex that's not held.</exception>
+        /// <param name="tokens">
+        /// The number of logical tokens to release.
+        /// </param>
+        /// <exception cref="ArgumentOutOfRangeException">
+        /// tokens must be 1.
+        /// </exception>
+        /// <exception cref="InvalidOperationException">
+        /// Cannot release a mutex that's not held.
+        /// </exception>
         public override void Release(int tokens)
         {
             if (tokens != 1)
             {
                 if (this.TokenCount > 0)
                 {
-                    throw new InvalidOperationException("Cannot release a mutex that's not held.");
+                    throw new InvalidOperationException(
+                        "Cannot release a mutex that's not held.");
                 }
                 else
                 {

File Cineraria.Concurrency/PairRendezvous.cs

         /// <summary>
         /// Object used for lock() blocks.
         /// </summary>
-        /// <remarks>See http://stackoverflow.com/questions/251391/why-is-lockthis-bad </remarks>
         private readonly object _syncRoot = new object();
 
         /// <summary>
-        /// Turnstile to prevent threads racing through <see cref="Exchange(T)"/>.
+        /// Turnstile to prevent threads racing through
+        /// <see cref="Exchange"/>.
         /// </summary>
         private Semaphore _turnstile = new Semaphore(1);
 
         private Semaphore _goPermission = new Semaphore(0);
 
         /// <summary>
-        /// A value indicating whether the current thread is the first thread to begin the exchange.
+        /// A value indicating whether the current thread is the first thread
+        /// to begin the exchange.
         /// </summary>
         private bool _isFirst = true;
 
         private T _held;
 
         /// <summary>
-        /// Initializes a new instance of the <see cref="PairRendezvous&lt;T&gt;"/> class.
+        /// Initializes a new instance of the
+        /// <see cref="PairRendezvous&lt;T&gt;"/> class.
         /// </summary>
         public PairRendezvous()
         {

File Cineraria.Concurrency/ReaderPriorityWriterLock.cs

         private readonly Lightswitch _readPermission;
 
         /// <summary>
-        /// Initializes a new instance of the <see cref="ReaderPriorityWriterLock"/> class.
+        /// Initializes a new instance of the
+        /// <see cref="ReaderPriorityWriterLock"/> class.
         /// </summary>
         public ReaderPriorityWriterLock()
         {

File Cineraria.Concurrency/ReaderWriterPriorityLock.cs

         private readonly Semaphore _writePermission = new Semaphore(1);
 
         /// <summary>
-        /// A turnstile used by readers so they're locked out when writers are queued.
+        /// A turnstile used by readers so they're locked out when writers are
+        /// queued.
         /// </summary>
         private readonly Semaphore _turnstile = new Semaphore(1);
 
         private readonly Lightswitch _readPermission;
 
         /// <summary>
-        /// A turnstile used by writers to lock out readers when writers are queued.
+        /// A turnstile used by writers to lock out readers when writers are
+        /// queued.
         /// </summary>
         private readonly Lightswitch _writerTurnstile;
 
         /// <summary>
-        /// Initializes a new instance of the <see cref="ReaderWriterPriorityLock"/> class.
+        /// Initializes a new instance of the
+        /// <see cref="ReaderWriterPriorityLock"/> class.
         /// </summary>
         public ReaderWriterPriorityLock()
         {

File Cineraria.Concurrency/Rendezvous.cs

         /// <summary>
         /// Object used for lock() blocks.
         /// </summary>
-        /// <remarks>See http://stackoverflow.com/questions/251391/why-is-lockthis-bad </remarks>
         private readonly object _syncRoot = new object();
 
         /// <summary>
         private readonly Semaphore _goPermission = new Semaphore(0);
 
         /// <summary>
-        /// The number of threads that must begin the exchange process for the exhange to continue.
+        /// The number of threads that must begin the exchange process for the
+        /// exhange to continue.
         /// </summary>
         private readonly int _threshold;
 
         private bool _isBroken = false;
 
         /// <summary>
-        /// Whether this rendezvous is open, ie. threshold was met and threads can leave.
+        /// Whether this rendezvous is open, ie. threshold was met and threads
+        /// can leave.
         /// </summary>
         private bool _isOpen = false;
 
         /// <summary>
-        /// Initializes a new instance of the <see cref="Rendezvous&lt;T&gt;"/> class.
+        /// Initializes a new instance of the <see cref="Rendezvous&lt;T&gt;"/>
+        /// class.
         /// </summary>
-        /// <param name="threshold">The number of threads that must begin the exchange process for the exhange to continue.</param>
+        /// <param name="threshold">The number of threads that must begin the
+        /// exchange process for the exhange to continue.</param>
         public Rendezvous(int threshold)
         {
             this._threshold = threshold;
                 }
             }
 
-            bool acquiredGoPermission = this._goPermission.Attempt(milliseconds);
+            bool acquiredGoPermission = this._goPermission.Acquire(
+                milliseconds);
 
             lock (this._syncRoot)
             {

File Cineraria.Concurrency/ThreadGroup.cs

         /// <summary>
         /// Object used for lock() blocks.
         /// </summary>
-        /// <remarks>See http://stackoverflow.com/questions/251391/why-is-lockthis-bad </remarks>
         private readonly object _syncRoot = new object();
 
         /// <summary>
         /// <summary>
         /// Starts all the threads in this group.
         /// </summary>
-        /// <exception cref="ThreadStateException">A thread has already been started.</exception>
+        /// <exception cref="ThreadStateException">
+        /// A thread has already been started.
+        /// </exception>
         public void StartAll()
         {
             lock (this._syncRoot)
         }
 
         /// <summary>
-        /// Starts all the threads in this group and waits until all are finished.
+        /// Starts all the threads in this group and waits until all are
+        /// finished.
         /// </summary>
         public void RunBlocking()
         {
         }
 
         /// <summary>
-        /// Adds multiple copies of a thread to this group that invoke the specified <see cref="Action"/>
-        /// with names of the form "<paramref name="namePrefix"/> THREAD_NUMBER".
+        /// Adds multiple copies of a thread to this group that invoke the
+        /// specified <see cref="Action"/> with names of the form
+        /// "<paramref name="namePrefix"/> THREAD_NUMBER".
         /// </summary>
-        /// <param name="del">The delegate invoked in each new thread. Takes a single argument (int threadNumber).</param>
+        /// <param name="del">
+        /// The delegate invoked in each new thread. Takes a single argument
+        /// (int threadNumber).
+        /// </param>
         /// <param name="count">The number of copies to add.</param>
-        /// <param name="namePrefix">The string used in the name of each new thread.</param>
-        /// <exception cref="ArgumentOutOfRangeException"><paramref name="count"/> must be a positive number.</exception>
+        /// <param name="namePrefix">
+        /// The string used in the name of each new thread.
+        /// </param>
+        /// <exception cref="ArgumentOutOfRangeException">
+        /// <paramref name="count"/> must be a positive number.
+        /// </exception>
         /// <returns>this (for chaining).</returns>
         public ThreadGroup AddMany(Action<int> del, int count, string namePrefix)
         {
                 for (int i = 0; i < count; i++)
                 {
                     int threadNumber = i;
-                    this._threads.Add(new Thread(() => del(threadNumber)) { Name = namePrefix + threadNumber.ToUIString() });
+                    this._threads.Add(new Thread(() => del(threadNumber))
+                        { Name = namePrefix + threadNumber.ToUIString() });
                 }
             }
 
         }
 
         /// <summary>
-        /// Adds a thread to this group that invokes the specified <see cref="Action"/>.
+        /// Adds a thread to this group that invokes the specified
+        /// <see cref="Action"/>.
         /// </summary>
         /// <param name="del">The delegate invoked in the new thread.</param>
         /// <param name="name">The name of the new thread.</param>

File Cineraria.Convenience/ColorHelper.cs

         /// <param name="hue">The hue value.</param>
         /// <param name="saturation">The saturation value.</param>
         /// <param name="brightness">The brightness value.</param>
-        /// <returns>An RGB colour equivalent to the specified AHSB values.</returns>
+        /// <returns>
+        /// An RGB colour equivalent to the specified AHSB values.
+        /// </returns>
         /// <remarks>
         /// Thanks to Steve from StackOverflow:
         /// http://stackoverflow.com/questions/1498832/colourizing-a-bitmap-in-net
         /// </remarks>
-        public static Color FromAhsb(int alpha, float hue, float saturation, float brightness)
+        public static Color FromAhsb(
+            int alpha,
+            float hue,
+            float saturation,
+            float brightness)
         {
             if (0 > alpha || 255 < alpha)
             {

File Cineraria.Net.Serve/ChannelServer.cs

         /// The channel that connections to listen to are put on for retrieval
         /// by the input listener thread(s).
         /// </summary>
-        private readonly SocketNotifyingChannel<RemoteClient> _inputListenChannel;
+        private readonly SocketNotifyingChannel<RemoteClient>
+            _inputListenChannel;
 
         /// <summary>
-        /// Initializes a new instance of the <see cref="ChannelServer"/> class.
+        /// Initializes a new instance of the <see cref="ChannelServer"/>
+        /// class.
         /// </summary>
         /// <param name="endPoint">
         /// The endpoint to listen for new connections on.
             this._endPoint = endPoint;
             this.EventChannel = new Channel<ConnectionEvent>();
             this._outputChannel = new Channel<ConnectionEvent>();
-            this._inputListenChannel = new SocketNotifyingChannel<RemoteClient>();
+            this._inputListenChannel =
+                new SocketNotifyingChannel<RemoteClient>();
         }
 
         /// <summary>
                     inputListenerThreads,
                     "Input Listener")
                 .AddMany(
-                    threadNumber => new OutputSender(this._outputChannel).Run(),
+                    threadNumber => new OutputSender(this._outputChannel)
+                        .Run(),
                     outputSenderThreads,
                     "Output Sender")
                 .StartAll();

File Cineraria.Net/TcpTextConnection.cs

     using System.Net.Sockets;
 
     /// <summary>
-    /// Provides client connections for TCP network services, and is capable of gracefully closing.
+    /// Provides client connections for TCP network services, and is capable of
+    /// gracefully closing.
     /// </summary>
     public class TcpTextConnection : IDisposable
     {
         private bool _disposed = false;
 
         /// <summary>
-        /// Initializes a new instance of the <see cref="TcpTextConnection"/> class that utilises the specified
-        /// already-connected <see cref="TcpClient"/>.
+        /// Initializes a new instance of the <see cref="TcpTextConnection"/>
+        /// class that utilises the specified already-connected
+        /// <see cref="TcpClient"/>.
         /// </summary>
-        /// <param name="client">An already-connected <see cref="TcpClient"/>.</param>
+        /// <param name="client">
+        /// An already-connected <see cref="TcpClient"/>.
+        /// </param>
         public TcpTextConnection(TcpClient client)
         {
             this.Client = client;
         }
 
         /// <summary>
-        /// Initializes a new instance of the <see cref="TcpTextConnection"/> class with a new
-        /// <see cref="System.Net.Sockets.TcpClient"/> and connects the client to a remote TCP host using the specified
-        /// IP addresses and port number.
+        /// Initializes a new instance of the <see cref="TcpTextConnection"/>
+        /// class with a new <see cref="TcpClient"/> and connects the client to
+        /// a remote TCP host using the specified IP addresses and port number.
         /// </summary>
-        /// <param name="address">The <see cref="System.Net.IPAddress"/> of the host to which you intend to connect.</param>
-        /// <param name="port">The port number to which you intend to connect.</param>
-        /// <exception cref="System.ArgumentNullException">The address parameter is null.</exception>
-        /// <exception cref="System.ArgumentOutOfRangeException">
-        /// The port is not between <see cref="System.Net.IPEndPoint.MinPort"/> and
-        /// <see cref="System.Net.IPEndPoint.MaxPort"/>.
+        /// <param name="address">
+        /// The <see cref="IPAddress"/> of the host to connect to.
+        /// </param>
+        /// <param name="port">
+        /// The remote port number to connect to.
+        /// </param>
+        /// <exception cref="ArgumentNullException">
+        /// The address parameter is null.
         /// </exception>
-        /// <exception cref="System.Net.Sockets.SocketException">An error occurred when accessing the socket.</exception>
+        /// <exception cref="ArgumentOutOfRangeException">
+        /// The port is not between <see cref="IPEndPoint.MinPort"/> and
+        /// <see cref="IPEndPoint.MaxPort"/>.
+        /// </exception>
+        /// <exception cref="SocketException">
+        /// An error occurred when accessing the socket.
+        /// </exception>
         public TcpTextConnection(IPAddress address, int port)
         {
             this.Client = new TcpClient();
         }
 
         /// <summary>
-        /// Gets the underlying <see cref="System.Net.Sockets.TcpClient"/> instance.
+        /// Gets the underlying <see cref="TcpClient"/> instance.
         /// </summary>
         public TcpClient Client { get; private set; }
 
         /// <summary>
-        /// Gets the underlying <see cref="System.Net.Sockets.Socket"/> instance.
+        /// Gets the underlying <see cref="Socket"/> instance.
         /// </summary>
         public Socket Socket
         {
         }
 
         /// <summary>
-        /// Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.
+        /// Performs application-defined tasks associated with freeing,
+        /// releasing, or resetting unmanaged resources.
         /// </summary>
         public void Dispose()
         {
         }
 
         /// <summary>
-        /// Disposes of this <see cref="TcpTextConnection"/> and closes the underlying TCP connection.
+        /// Disposes of this <see cref="TcpTextConnection"/> and closes the
+        /// underlying TCP connection.
         /// </summary>
-        /// <param name="disposing"><c>true</c> to release both managed and unmanaged resources; <c>false</c> to release only unmanaged resources.</param>
-        /// <exception cref="System.Net.Sockets.SocketException">An error occurred when attempting to access the socket.</exception>
+        /// <param name="disposing">
+        /// <c>true</c> to release both managed and unmanaged resources;
+        /// <c>false</c> to release only unmanaged resources.
+        /// </param>
+        /// <exception cref="SocketException">
+        /// An error occurred when attempting to access the socket.
+        /// </exception>
         protected virtual void Dispose(bool disposing)
         {
             if (!this._disposed && disposing)
                 }
                 catch (IOException)
                 {
-                    // If there's a read error we'll forcefully close the connection below.
+                    // If there's a read error we'll forcefully close the
+                    // connection below.
                 }
                 finally
                 {

File ConcurrencyTests/LightswitchTest.cs

         /// <summary>
         /// The semaphore used in the lightswitch.
         /// </summary>
-        private static ISync _innerPermission = new Semaphore(1);
+        private static Semaphore _innerPermission = new Semaphore(1);
 
         /// <summary>
         /// The <see cref="Lightswitch"/> instance to test.