From 213b0ff14bc419a1784cc7685a32822f2256ab37 Mon Sep 17 00:00:00 2001
From: Davis King <davis@dlib.net>
Date: Fri, 28 Dec 2012 17:11:44 -0500
Subject: [PATCH] Added speed information about the pipe and bridge

---
 docs/docs/network.xml | 22 ++++++++++++++++++++++
 docs/docs/other.xml   | 19 +++++++++++++++++--
 2 files changed, 39 insertions(+), 2 deletions(-)

diff --git a/docs/docs/network.xml b/docs/docs/network.xml
index 6ad4ec26f..8194632f8 100644
--- a/docs/docs/network.xml
+++ b/docs/docs/network.xml
@@ -73,6 +73,28 @@
          <description>
             This object is a tool for bridging a <a href="other.html#pipe">pipe</a> object between
             two network connected applications.  
+
+            <p>
+               The bridge object is designed to link two pipes together as efficiently as
+               possible.  To demonstrate its speed, I ran two experiments where a bridge was
+               used to connect a desktop PC to a laptop, both running Ubuntu 12.04 and
+               connected via gigabit ethernet.  The first experiment is to test its bulk
+               transfer speed while the second experiment measures how many separate objects
+               the bridge can transfer each second.
+            </p>
+            <p>
+               In the first experiment, 1-megapixel images, represented with
+               <tt>array&lt;rgb_pixel&gt;</tt> objects, were sent.  The transfer rate was
+               112 megabytes/second, saturating the gigabit ethernet link.  The second
+               experiment used a <tt>pipe&lt;char&gt;</tt> and <tt>bridge</tt> to send individual
+               <tt>char</tt> variables over the network.  In this experiment, I was able to
+               send 3.2 million objects a second (i.e. the receiving end was getting a char
+               back from pipe::dequeue() 3.2 million times each second).
+            </p>
+            <p>
+               For reference, these experiments were carried out on a desktop with a 2.67GHz
+               Intel Core-i7 CPU and a laptop with a 2.20GHz Intel Core-i7 CPU.
+            </p>
          </description>
          <examples>
             <example>bridge_ex.cpp.html</example>
diff --git a/docs/docs/other.xml b/docs/docs/other.xml
index 0aa409fb6..ed2669f67 100644
--- a/docs/docs/other.xml
+++ b/docs/docs/other.xml
@@ -331,8 +331,23 @@
          <file>dlib/pipe.h</file>
          <spec_file>dlib/pipe/pipe_kernel_abstract.h</spec_file>
          <description>
-                This is a first in first out queue with a fixed maximum size containing items 
-                of type T.  It is suitable for passing objects between threads.
+                This is a first in first out queue with a fixed maximum size.  
+                It is suitable for passing objects between threads.
+
+               <p>
+                  This object is optimized for speed, therefore, it uses
+                  global <tt>swap()</tt> to create a zero-copy method for moving objects
+                  around.  For example, on a computer running Ubuntu 12.04 with
+                  a 2.67GHz Intel i7 920 CPU it is possible to pass over 4.4
+                  million <tt>std::vector&lt;int&gt;</tt> objects a second between two
+                  threads.  This is regardless of the number of ints in the <tt>std::vector</tt>
+                  objects.  In particular, this test was done with 100,000 
+                  ints in each <tt>std::vector</tt>.
+               </p>
+               <p>
+                  Finally, note that you can use the pipe as an efficient method to pass
+                  messages between two networked computers by using the <a href="network.html#bridge">bridge</a>.
+               </p>
          </description>
          
          <examples>