Adding comments to meaningless field names

Author: lodejard

src/Microsoft.AspNet.Server.Kestrel/Http/ListenerPrimary.cs

@@ -17,7 +17,10 @@ abstract public class ListenerPrimary : Listener
     {
         private List<UvPipeHandle> _dispatchPipes = new List<UvPipeHandle>();
         private int _dispatchIndex;
-        private ArraySegment<ArraySegment<byte>> _binaryOneTwoThreeFour = new ArraySegment<ArraySegment<byte>>(new[] { new ArraySegment<byte>(new byte[] { 1, 2, 3, 4 }) });
+
+        // this message is passed to write2 because it must be non-zero-length, 
+        // but it has no other functional significance
+        private readonly ArraySegment<ArraySegment<byte>> _dummyMessage = new ArraySegment<ArraySegment<byte>>(new[] { new ArraySegment<byte>(new byte[] { 1, 2, 3, 4 }) });
 
         protected ListenerPrimary(IMemoryPool memory) : base(memory)
         {
@@ -79,7 +82,7 @@ protected override void DispatchConnection(UvStreamHandle socket)
                 write.Init(Thread.Loop);
                 write.Write2(
                     dispatchPipe,
-                    _binaryOneTwoThreeFour,
+                    _dummyMessage,
                     socket,
                     (write2, status, error, state) => 
                     {

src/Microsoft.AspNet.Server.Kestrel/Infrastructure/KestrelThread.cs

@@ -16,7 +16,7 @@ namespace Microsoft.AspNet.Server.Kestrel
     /// </summary>
     public class KestrelThread
     {
-        private static Action<object, object> _objectCallback = (cb, obj) => ((Action<object>)cb).Invoke(obj);
+        private static Action<object, object> _objectCallbackAdapter = (callback, state) => ((Action<object>)callback).Invoke(state);
         private KestrelEngine _engine;
         private Thread _thread;
         private UvLoopHandle _loop;
@@ -103,7 +103,7 @@ public void Post(Action<object> callback, object state)
         {
             lock (_workSync)
             {
-                _workAdding.Enqueue(new Work { Callback1 = _objectCallback, Callback2 = callback, State = state });
+                _workAdding.Enqueue(new Work { CallbackAdapter = _objectCallbackAdapter, Callback = callback, State = state });
             }
             _post.Send();
         }
@@ -114,8 +114,8 @@ public void Post<T>(Action<T> callback, T state)
             {
                 _workAdding.Enqueue(new Work
                 {
-                    Callback1 = (state1, state2) => ((Action<T>)state1).Invoke((T)state2),
-                    Callback2 = callback,
+                    CallbackAdapter = (callback2, state2) => ((Action<T>)callback2).Invoke((T)state2),
+                    Callback = callback,
                     State = state
                 });
             }
@@ -129,8 +129,8 @@ public Task PostAsync(Action<object> callback, object state)
             {
                 _workAdding.Enqueue(new Work
                 {
-                    Callback1 = _objectCallback,
-                    Callback2 = callback,
+                    CallbackAdapter = _objectCallbackAdapter,
+                    Callback = callback,
                     State = state,
                     Completion = tcs
                 });
@@ -146,8 +146,8 @@ public Task PostAsync<T>(Action<T> callback, T state)
             {
                 _workAdding.Enqueue(new Work
                 {
-                    Callback1 = (state1, state2) => ((Action<T>)state1).Invoke((T)state2),
-                    Callback2 = callback,
+                    CallbackAdapter = (state1, state2) => ((Action<T>)state1).Invoke((T)state2),
+                    Callback = callback,
                     State = state,
                     Completion = tcs
                 });
@@ -250,7 +250,7 @@ private void DoPostWork()
                 var work = queue.Dequeue();
                 try
                 {
-                    work.Callback1(work.Callback2, work.State);
+                    work.CallbackAdapter(work.Callback, work.State);
                     if (work.Completion != null)
                     {
                         ThreadPool.QueueUserWorkItem(
@@ -299,8 +299,8 @@ private void DoPostCloseHandle()
 
         private struct Work
         {
-            public Action<object, object> Callback1;
-            public object Callback2;
+            public Action<object, object> CallbackAdapter;
+            public object Callback;
             public object State;
             public TaskCompletionSource<int> Completion;
         }

src/Microsoft.AspNet.Server.Kestrel/Networking/Libuv.cs

@@ -395,6 +395,11 @@ public uv_buf_t buf_init(IntPtr memory, int len)
 
         public struct sockaddr
         {
+            // this type represents native memory occupied by sockaddr struct
+            // https://msdn.microsoft.com/en-us/library/windows/desktop/ms740496(v=vs.85).aspx
+            // although the c/c++ header defines it as a 2-byte short followed by a 14-byte array,
+            // the simplest way to reserve the same size in c# is with four nameless long values
+
             private long _field0;
             private long _field1;
             private long _field2;
@@ -405,8 +410,16 @@ public struct sockaddr
 
         public struct uv_buf_t
         {
-            public IntPtr _field0;
-            public IntPtr _field1;
+            // this type represents a WSABUF struct on Windows 
+            // https://msdn.microsoft.com/en-us/library/windows/desktop/ms741542(v=vs.85).aspx
+            // and an iovec struct on *nix
+            // http://man7.org/linux/man-pages/man2/readv.2.html
+            // because the order of the fields in these structs is different, the field
+            // names in this type don't have meaningful symbolic names. instead, they are
+            // assigned in the correct order by the constructor at runtime
+
+            private readonly IntPtr _field0;
+            private readonly IntPtr _field1;
 
             public uv_buf_t(IntPtr memory, int len, bool IsWindows)
             {