Added try_receive() routines to the bsp_context object.

dlib/bsp/bsp.h

@@ -420,16 +420,35 @@ namespace dlib
         }
 
         template <typename T>
-        bool receive (
+        void receive (
+            T& item
+        ) 
+        {
+            if(!try_receive(item))
+                throw dlib::socket_error("bsp_context::receive(): no messages to receive, all nodes currently blocked.");
+        }
+
+        template <typename T>
+        bool try_receive (
             T& item
         ) 
         {
             unsigned long sending_node_id;
-            return receive(item, sending_node_id);
+            return try_receive(item, sending_node_id);
+        }
+
+        template <typename T>
+        void receive (
+            T& item,
+            unsigned long& sending_node_id
+        ) 
+        {
+            if(!try_receive(item, sending_node_id))
+                throw dlib::socket_error("bsp_context::receive(): no messages to receive, all nodes currently blocked.");
         }
 
         template <typename T>
-        bool receive (
+        bool try_receive (
             T& item,
             unsigned long& sending_node_id
         ) 

dlib/bsp/bsp_abstract.h

@@ -102,7 +102,7 @@ namespace dlib
         !*/
 
         template <typename T>
-        bool receive (
+        bool try_receive (
             T& item
         );
         /*!
@@ -114,17 +114,44 @@ namespace dlib
                       node.
                 - else
                     - The following must have been true for this function to return false:
-                        - All other nodes were blocked on calls to receive() or terminated.
+                        - All other nodes were blocked on calls to receive(),
+                          try_receive(), or have terminated.
                         - There were not any messages in flight between any nodes.  
-                        - That is, if all the nodes had continued to block on receive()
-                          then they all would have blocked forever.  Therefore, this
-                          function only returns once there are no more messages to process
-                          by any any node and there is no possibility of more being
-                          generated until control is returned to the callers of receive(). 
+                        - That is, if all the nodes had continued to block on receive
+                          methods then they all would have blocked forever.  Therefore,
+                          this function only returns false once there are no more messages
+                          to process by any node and there is no possibility of more being
+                          generated until control is returned to the callers of receive
+                          methods. 
             throws
                 - dlib::socket_error:
                     This exception is thrown if some error occurs which prevents us from
                     communicating with other processing nodes.
+                - dlib::serialization_error or any exception thrown by the global
+                  deserialize(T) routine:
+                    This is thrown if there is a problem in deserialize().  This might
+                    happen if the message sent doesn't match the type T expected by
+                    try_receive().
+        !*/
+
+        template <typename T>
+        void receive (
+            T& item
+        );
+        /*!
+            requires
+                - item is serializable
+            ensures
+                - #item == the next message which was sent to the calling processing
+                  node.
+                - This function is just a wrapper around try_receive() that throws an
+                  exception if a message is not received (i.e. if try_receive() returns
+                  false).
+            throws
+                - dlib::socket_error:
+                    This exception is thrown if some error occurs which prevents us from
+                    communicating with other processing nodes or if there was not a message
+                    to receive.
                 - dlib::serialization_error or any exception thrown by the global
                   deserialize(T) routine:
                     This is thrown if there is a problem in deserialize().  This might
@@ -133,7 +160,7 @@ namespace dlib
         !*/
 
         template <typename T>
-        bool receive (
+        bool try_receive (
             T& item,
             unsigned long& sending_node_id
         ); 
@@ -148,17 +175,46 @@ namespace dlib
                     - #sending_node_id < number_of_nodes()
                 - else
                     - The following must have been true for this function to return false:
-                        - All other nodes were blocked on calls to receive() or terminated.
+                        - All other nodes were blocked on calls to receive(),
+                          try_receive(), or have terminated.
                         - There were not any messages in flight between any nodes.  
-                        - That is, if all the nodes had continued to block on receive()
-                          then they all would have blocked forever.  Therefore, this
-                          function only returns once there are no more messages to process
-                          by any any node and there is no possibility of more being
-                          generated until control is returned to the callers of receive(). 
+                        - That is, if all the nodes had continued to block on receive
+                          methods then they all would have blocked forever.  Therefore,
+                          this function only returns false once there are no more messages
+                          to process by any node and there is no possibility of more being
+                          generated until control is returned to the callers of receive
+                          methods. 
             throws
                 - dlib::socket_error:
                     This exception is thrown if some error occurs which prevents us from
                     communicating with other processing nodes.
+                - dlib::serialization_error or any exception thrown by the global
+                  deserialize(T) routine:
+                    This is thrown if there is a problem in deserialize().  This might
+                    happen if the message sent doesn't match the type T expected by
+                    try_receive().
+        !*/
+
+        template <typename T>
+        void receive (
+            T& item,
+            unsigned long& sending_node_id
+        ); 
+        /*!
+            requires
+                - item is serializable
+            ensures
+                - #item == the next message which was sent to the calling processing node.
+                - #sending_node_id == the node id of the node that sent this message.
+                - #sending_node_id < number_of_nodes()
+                - This function is just a wrapper around try_receive() that throws an
+                  exception if a message is not received (i.e. if try_receive() returns
+                  false).
+            throws
+                - dlib::socket_error:
+                    This exception is thrown if some error occurs which prevents us from
+                    communicating with other processing nodes or if there was not a message
+                    to receive.
                 - dlib::serialization_error or any exception thrown by the global
                   deserialize(T) routine:
                     This is thrown if there is a problem in deserialize().  This might
@@ -175,8 +231,8 @@ namespace dlib
                     - There are not any messages in flight between any nodes.  
                     - That is, if all the nodes had continued to block on receive() then
                       they all would have blocked forever.  Therefore, this function only
-                      returns once there are no more messages to process by any any node
-                      and there is no possibility of more being generated until control is
+                      returns once there are no more messages to process by any node and
+                      there is no possibility of more being generated until control is
                       returned to the callers of receive(). 
             throws
                 - dlib::socket_error:

dlib/test/bsp.cpp

@@ -114,7 +114,7 @@ namespace
 
         result = 0;
         int val;
-        while(obj.receive(val))
+        while(obj.try_receive(val))
             result += val;
     }
 
@@ -227,24 +227,24 @@ namespace
 
         int accum = 0;
         int temp = 0;
-        while(obj.receive(temp))
+        while(obj.try_receive(temp))
             accum += temp;
 
         // send to node 1 so it can sum everything
         if (obj.node_id() != 1)
             obj.send(accum, 1);
 
-        while(obj.receive(temp))
+        while(obj.try_receive(temp))
             accum += temp;
 
         // Now hop the accum values along the nodes until the value from node 1 gets to
         // node 0.
         obj.send(accum, (obj.node_id()+1)%obj.number_of_nodes());
-        DLIB_TEST(obj.receive(accum));
+        obj.receive(accum);
         obj.send(accum, (obj.node_id()+1)%obj.number_of_nodes());
-        DLIB_TEST(obj.receive(accum));
+        obj.receive(accum);
         obj.send(accum, (obj.node_id()+1)%obj.number_of_nodes());
-        DLIB_TEST(obj.receive(accum));
+        obj.receive(accum);
 
         // this whole block is a noop since it doesn't end up doing anything.
         for (int k = 0; k < 100; ++k)
@@ -253,7 +253,7 @@ namespace
             for (int i = 0; i < 4; ++i)
             {
                 obj.send(accum, (obj.node_id()+1)%obj.number_of_nodes());
-                DLIB_TEST(obj.receive(accum));
+                obj.receive(accum);
             }
         }
 
@@ -317,24 +317,24 @@ namespace
 
         int accum = 0;
         int temp = 0;
-        while(obj.receive(temp))
+        while(obj.try_receive(temp))
             accum += temp;
 
         // send to node 1 so it can sum everything
         if (obj.node_id() != 1)
             obj.send(accum, 1);
 
-        while(obj.receive(temp))
+        while(obj.try_receive(temp))
             accum += temp;
 
         // Now hop the accum values along the nodes until the value from node 1 gets to
         // node 0.
         obj.send(accum, (obj.node_id()+1)%obj.number_of_nodes());
-        DLIB_TEST(obj.receive(accum));
+        obj.receive(accum);
         obj.send(accum, (obj.node_id()+1)%obj.number_of_nodes());
-        DLIB_TEST(obj.receive(accum));
+        obj.receive(accum);
         obj.send(accum, (obj.node_id()+1)%obj.number_of_nodes());
-        DLIB_TEST(obj.receive(accum));
+        obj.receive(accum);
 
         // this whole block is a noop since it doesn't end up doing anything.
         for (int k = 0; k < 40; ++k)
@@ -343,7 +343,7 @@ namespace
             for (int i = 0; i < 4; ++i)
             {
                 obj.send(accum, (obj.node_id()+1)%obj.number_of_nodes());
-                DLIB_TEST_MSG(obj.receive(accum), obj.node_id());
+                obj.receive(accum);
 
                 obj.receive();
             }
@@ -415,12 +415,15 @@ namespace
         void perform_test (
         )
         {
-            dotest1();
-            dotest2<0>();
-            dotest2<1>();
-            dotest2<2>();
-            dotest3();
-            dotest4();
+            for (int i = 0; i < 3; ++i)
+            {
+                dotest1();
+                dotest2<0>();
+                dotest2<1>();
+                dotest2<2>();
+                dotest3();
+                dotest4();
+            }
         }
     } a;