|
<html><head><title>dlib C++ Library - bsp_abstract.h</title></head><body bgcolor='white'><pre> |
|
<font color='#009900'>// Copyright (C) 2012 Davis E. King ([email protected]) |
|
</font><font color='#009900'>// License: Boost Software License See LICENSE.txt for the full license. |
|
</font><font color='#0000FF'>#undef</font> DLIB_BsP_ABSTRACT_Hh_ |
|
<font color='#0000FF'>#ifdef</font> DLIB_BsP_ABSTRACT_Hh_ |
|
|
|
<font color='#0000FF'>#include</font> "<a style='text-decoration:none' href='../noncopyable.h.html'>../noncopyable.h</a>" |
|
<font color='#0000FF'>#include</font> "<a style='text-decoration:none' href='../sockets/sockets_extensions_abstract.h.html'>../sockets/sockets_extensions_abstract.h</a>" |
|
<font color='#0000FF'>#include</font> <font color='#5555FF'><</font>vector<font color='#5555FF'>></font> |
|
|
|
<font color='#0000FF'>namespace</font> dlib |
|
<b>{</b> |
|
|
|
<font color='#009900'>// ---------------------------------------------------------------------------------------- |
|
</font> |
|
<font color='#0000FF'>class</font> <b><a name='bsp_context'></a>bsp_context</b> : noncopyable |
|
<b>{</b> |
|
<font color='#009900'>/*! |
|
WHAT THIS OBJECT REPRESENTS |
|
This is a tool used to implement algorithms using the Bulk Synchronous |
|
Parallel (BSP) computing model. A BSP algorithm is composed of a number of |
|
processing nodes, each executing in parallel. The general flow of |
|
execution in each processing node is the following: |
|
1. Do work locally on some data. |
|
2. Send some messages to other nodes. |
|
3. Receive messages from other nodes. |
|
4. Go to step 1 or terminate if complete. |
|
|
|
To do this, each processing node needs an API used to send and receive |
|
messages. This API is implemented by the bsp_connect object which provides |
|
these services to a BSP node. |
|
|
|
Note that BSP processing nodes are spawned using the bsp_connect() and |
|
bsp_listen() routines defined at the bottom of this file. For example, to |
|
start a BSP algorithm consisting of N processing nodes, you would make N-1 |
|
calls to bsp_listen() and one call to bsp_connect(). The call to |
|
bsp_connect() then initiates the computation on all nodes. |
|
|
|
Finally, note that there is no explicit barrier synchronization function |
|
you call at the end of step 3. Instead, you can simply call a method such |
|
as try_receive() until it returns false. That is, the bsp_context's |
|
receive methods incorporate a barrier synchronization that happens once all |
|
the BSP nodes are blocked on receive calls and there are no more messages |
|
in flight. |
|
|
|
|
|
THREAD SAFETY |
|
This object is not thread-safe. In particular, you should only ever have |
|
one thread that works with an instance of this object. This means that, |
|
for example, you should not spawn sub-threads from within a BSP processing |
|
node and have them invoke methods on this object. Instead, you should only |
|
invoke this object's methods from within the BSP processing node's main |
|
thread (i.e. the thread that executes the user supplied function funct()). |
|
!*/</font> |
|
|
|
<font color='#0000FF'>public</font>: |
|
|
|
<font color='#0000FF'>template</font> <font color='#5555FF'><</font><font color='#0000FF'>typename</font> T<font color='#5555FF'>></font> |
|
<font color='#0000FF'><u>void</u></font> <b><a name='send'></a>send</b><font face='Lucida Console'>(</font> |
|
<font color='#0000FF'>const</font> T<font color='#5555FF'>&</font> item, |
|
<font color='#0000FF'><u>unsigned</u></font> <font color='#0000FF'><u>long</u></font> target_node_id |
|
<font face='Lucida Console'>)</font>; |
|
<font color='#009900'>/*! |
|
requires |
|
- item is serializable |
|
- target_node_id < number_of_nodes() |
|
- target_node_id != node_id() |
|
ensures |
|
- sends a copy of item to the node with the given id. |
|
throws |
|
- dlib::socket_error: |
|
This exception is thrown if there is an error which prevents us from |
|
delivering the message to the given node. One way this might happen is |
|
if the target node has already terminated its execution or has lost |
|
network connectivity. |
|
!*/</font> |
|
|
|
<font color='#0000FF'>template</font> <font color='#5555FF'><</font><font color='#0000FF'>typename</font> T<font color='#5555FF'>></font> |
|
<font color='#0000FF'><u>void</u></font> <b><a name='broadcast'></a>broadcast</b> <font face='Lucida Console'>(</font> |
|
<font color='#0000FF'>const</font> T<font color='#5555FF'>&</font> item |
|
<font face='Lucida Console'>)</font>; |
|
<font color='#009900'>/*! |
|
ensures |
|
- item is serializable |
|
- sends a copy of item to all other processing nodes. |
|
throws |
|
- dlib::socket_error |
|
This exception is thrown if there is an error which prevents us from |
|
delivering a message to one of the other nodes. This might happen, for |
|
example, if one of the nodes has terminated its execution or has lost |
|
network connectivity. |
|
!*/</font> |
|
|
|
<font color='#0000FF'><u>unsigned</u></font> <font color='#0000FF'><u>long</u></font> <b><a name='node_id'></a>node_id</b> <font face='Lucida Console'>(</font> |
|
<font face='Lucida Console'>)</font> <font color='#0000FF'>const</font>; |
|
<font color='#009900'>/*! |
|
ensures |
|
- Returns the id of the current processing node. That is, |
|
returns a number N such that: |
|
- N < number_of_nodes() |
|
- N == the node id of the processing node that called node_id(). This |
|
is a number that uniquely identifies the processing node. |
|
!*/</font> |
|
|
|
<font color='#0000FF'><u>unsigned</u></font> <font color='#0000FF'><u>long</u></font> <b><a name='number_of_nodes'></a>number_of_nodes</b> <font face='Lucida Console'>(</font> |
|
<font face='Lucida Console'>)</font> <font color='#0000FF'>const</font>; |
|
<font color='#009900'>/*! |
|
ensures |
|
- returns the number of processing nodes participating in the BSP |
|
computation. |
|
!*/</font> |
|
|
|
<font color='#0000FF'>template</font> <font color='#5555FF'><</font><font color='#0000FF'>typename</font> T<font color='#5555FF'>></font> |
|
<font color='#0000FF'><u>bool</u></font> <b><a name='try_receive'></a>try_receive</b> <font face='Lucida Console'>(</font> |
|
T<font color='#5555FF'>&</font> item |
|
<font face='Lucida Console'>)</font>; |
|
<font color='#009900'>/*! |
|
requires |
|
- item is serializable |
|
ensures |
|
- if (this function returns true) then |
|
- #item == the next message which was sent to the calling processing |
|
node. |
|
- else |
|
- The following must have been true for this function to return false: |
|
- 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 |
|
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. |
|
- When one BSP node's receive method returns because of the above |
|
conditions then all of them will also return. That is, it is NOT the |
|
case that just a subset of BSP nodes unblock. Moreover, they all |
|
unblock at the same time. |
|
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(). |
|
!*/</font> |
|
|
|
<font color='#0000FF'>template</font> <font color='#5555FF'><</font><font color='#0000FF'>typename</font> T<font color='#5555FF'>></font> |
|
<font color='#0000FF'><u>void</u></font> <b><a name='receive'></a>receive</b> <font face='Lucida Console'>(</font> |
|
T<font color='#5555FF'>&</font> item |
|
<font face='Lucida Console'>)</font>; |
|
<font color='#009900'>/*! |
|
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 |
|
happen if the message sent doesn't match the type T expected by |
|
receive(). |
|
!*/</font> |
|
|
|
<font color='#0000FF'>template</font> <font color='#5555FF'><</font><font color='#0000FF'>typename</font> T<font color='#5555FF'>></font> |
|
<font color='#0000FF'><u>bool</u></font> <b><a name='try_receive'></a>try_receive</b> <font face='Lucida Console'>(</font> |
|
T<font color='#5555FF'>&</font> item, |
|
<font color='#0000FF'><u>unsigned</u></font> <font color='#0000FF'><u>long</u></font><font color='#5555FF'>&</font> sending_node_id |
|
<font face='Lucida Console'>)</font>; |
|
<font color='#009900'>/*! |
|
requires |
|
- item is serializable |
|
ensures |
|
- if (this function returns true) then |
|
- #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() |
|
- else |
|
- The following must have been true for this function to return false: |
|
- 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 |
|
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. |
|
- When one BSP node's receive method returns because of the above |
|
conditions then all of them will also return. That is, it is NOT the |
|
case that just a subset of BSP nodes unblock. Moreover, they all |
|
unblock at the same time. |
|
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(). |
|
!*/</font> |
|
|
|
<font color='#0000FF'>template</font> <font color='#5555FF'><</font><font color='#0000FF'>typename</font> T<font color='#5555FF'>></font> |
|
<font color='#0000FF'><u>void</u></font> <b><a name='receive'></a>receive</b> <font face='Lucida Console'>(</font> |
|
T<font color='#5555FF'>&</font> item, |
|
<font color='#0000FF'><u>unsigned</u></font> <font color='#0000FF'><u>long</u></font><font color='#5555FF'>&</font> sending_node_id |
|
<font face='Lucida Console'>)</font>; |
|
<font color='#009900'>/*! |
|
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 |
|
happen if the message sent doesn't match the type T expected by |
|
receive(). |
|
!*/</font> |
|
|
|
<font color='#0000FF'><u>void</u></font> <b><a name='receive'></a>receive</b> <font face='Lucida Console'>(</font> |
|
<font face='Lucida Console'>)</font>; |
|
<font color='#009900'>/*! |
|
ensures |
|
- Waits for the following to all be true: |
|
- All other nodes were blocked on calls to receive(), try_receive(), or |
|
have terminated. |
|
- There are not any messages in flight between any nodes. |
|
- 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 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. |
|
- When one BSP node's receive method returns because of the above |
|
conditions then all of them will also return. That is, it is NOT the |
|
case that just a subset of BSP nodes unblock. Moreover, they all unblock |
|
at the same time. |
|
throws |
|
- dlib::socket_error: |
|
This exception is thrown if some error occurs which prevents us from |
|
communicating with other processing nodes or if a message is received |
|
before this function would otherwise return. |
|
|
|
!*/</font> |
|
|
|
<b>}</b>; |
|
|
|
<font color='#009900'>// ---------------------------------------------------------------------------------------- |
|
</font><font color='#009900'>// ---------------------------------------------------------------------------------------- |
|
</font> |
|
<font color='#0000FF'>template</font> <font color='#5555FF'><</font> |
|
<font color='#0000FF'>typename</font> funct_type |
|
<font color='#5555FF'>></font> |
|
<font color='#0000FF'><u>void</u></font> <b><a name='bsp_connect'></a>bsp_connect</b> <font face='Lucida Console'>(</font> |
|
<font color='#0000FF'>const</font> std::vector<font color='#5555FF'><</font>network_address<font color='#5555FF'>></font><font color='#5555FF'>&</font> hosts, |
|
funct_type funct |
|
<font face='Lucida Console'>)</font>; |
|
<font color='#009900'>/*! |
|
requires |
|
- let CONTEXT be an instance of a bsp_context object. Then: |
|
- funct(CONTEXT) must be a valid expression |
|
(i.e. funct must be a function or function object) |
|
ensures |
|
- This function spawns a BSP job consisting of hosts.size()+1 processing nodes. |
|
- The processing node with a node ID of 0 will run locally on the machine |
|
calling bsp_connect(). In particular, this node will execute funct(CONTEXT), |
|
which is expected to carry out this node's portion of the BSP computation. |
|
- The other processing nodes are executed on the hosts indicated by the input |
|
argument. In particular, this function interprets hosts as a list addresses |
|
identifying machines running the bsp_listen() or bsp_listen_dynamic_port() |
|
routines. |
|
- This call to bsp_connect() blocks until the BSP computation has completed on |
|
all processing nodes. |
|
throws |
|
- dlib::socket_error |
|
This exception is thrown if there is an error which prevents the BSP |
|
job from executing. |
|
- Any exception thrown by funct() will be propagated out of this call to |
|
bsp_connect(). |
|
!*/</font> |
|
|
|
<font color='#009900'>// ---------------------------------------------------------------------------------------- |
|
</font> |
|
<font color='#0000FF'>template</font> <font color='#5555FF'><</font> |
|
<font color='#0000FF'>typename</font> funct_type, |
|
<font color='#0000FF'>typename</font> ARG1 |
|
<font color='#5555FF'>></font> |
|
<font color='#0000FF'><u>void</u></font> <b><a name='bsp_connect'></a>bsp_connect</b> <font face='Lucida Console'>(</font> |
|
<font color='#0000FF'>const</font> std::vector<font color='#5555FF'><</font>network_address<font color='#5555FF'>></font><font color='#5555FF'>&</font> hosts, |
|
funct_type funct, |
|
ARG1 arg1 |
|
<font face='Lucida Console'>)</font>; |
|
<font color='#009900'>/*! |
|
requires |
|
- let CONTEXT be an instance of a bsp_context object. Then: |
|
- funct(CONTEXT,arg1) must be a valid expression |
|
(i.e. funct must be a function or function object) |
|
ensures |
|
- This function spawns a BSP job consisting of hosts.size()+1 processing nodes. |
|
- The processing node with a node ID of 0 will run locally on the machine |
|
calling bsp_connect(). In particular, this node will execute funct(CONTEXT,arg1), |
|
which is expected to carry out this node's portion of the BSP computation. |
|
- The other processing nodes are executed on the hosts indicated by the input |
|
argument. In particular, this function interprets hosts as a list addresses |
|
identifying machines running the bsp_listen() or bsp_listen_dynamic_port() |
|
routines. |
|
- This call to bsp_connect() blocks until the BSP computation has completed on |
|
all processing nodes. |
|
throws |
|
- dlib::socket_error |
|
This exception is thrown if there is an error which prevents the BSP |
|
job from executing. |
|
- Any exception thrown by funct() will be propagated out of this call to |
|
bsp_connect(). |
|
!*/</font> |
|
|
|
<font color='#009900'>// ---------------------------------------------------------------------------------------- |
|
</font> |
|
<font color='#0000FF'>template</font> <font color='#5555FF'><</font> |
|
<font color='#0000FF'>typename</font> funct_type, |
|
<font color='#0000FF'>typename</font> ARG1, |
|
<font color='#0000FF'>typename</font> ARG2 |
|
<font color='#5555FF'>></font> |
|
<font color='#0000FF'><u>void</u></font> <b><a name='bsp_connect'></a>bsp_connect</b> <font face='Lucida Console'>(</font> |
|
<font color='#0000FF'>const</font> std::vector<font color='#5555FF'><</font>network_address<font color='#5555FF'>></font><font color='#5555FF'>&</font> hosts, |
|
funct_type funct, |
|
ARG1 arg1, |
|
ARG2 arg2 |
|
<font face='Lucida Console'>)</font>; |
|
<font color='#009900'>/*! |
|
requires |
|
- let CONTEXT be an instance of a bsp_context object. Then: |
|
- funct(CONTEXT,arg1,arg2) must be a valid expression |
|
(i.e. funct must be a function or function object) |
|
ensures |
|
- This function spawns a BSP job consisting of hosts.size()+1 processing nodes. |
|
- The processing node with a node ID of 0 will run locally on the machine |
|
calling bsp_connect(). In particular, this node will execute funct(CONTEXT,arg1,arg2), |
|
which is expected to carry out this node's portion of the BSP computation. |
|
- The other processing nodes are executed on the hosts indicated by the input |
|
argument. In particular, this function interprets hosts as a list addresses |
|
identifying machines running the bsp_listen() or bsp_listen_dynamic_port() |
|
routines. |
|
- This call to bsp_connect() blocks until the BSP computation has completed on |
|
all processing nodes. |
|
throws |
|
- dlib::socket_error |
|
This exception is thrown if there is an error which prevents the BSP |
|
job from executing. |
|
- Any exception thrown by funct() will be propagated out of this call to |
|
bsp_connect(). |
|
!*/</font> |
|
|
|
<font color='#009900'>// ---------------------------------------------------------------------------------------- |
|
</font> |
|
<font color='#0000FF'>template</font> <font color='#5555FF'><</font> |
|
<font color='#0000FF'>typename</font> funct_type, |
|
<font color='#0000FF'>typename</font> ARG1, |
|
<font color='#0000FF'>typename</font> ARG2, |
|
<font color='#0000FF'>typename</font> ARG3 |
|
<font color='#5555FF'>></font> |
|
<font color='#0000FF'><u>void</u></font> <b><a name='bsp_connect'></a>bsp_connect</b> <font face='Lucida Console'>(</font> |
|
<font color='#0000FF'>const</font> std::vector<font color='#5555FF'><</font>network_address<font color='#5555FF'>></font><font color='#5555FF'>&</font> hosts, |
|
funct_type funct, |
|
ARG1 arg1, |
|
ARG2 arg2, |
|
ARG3 arg3 |
|
<font face='Lucida Console'>)</font>; |
|
<font color='#009900'>/*! |
|
requires |
|
- let CONTEXT be an instance of a bsp_context object. Then: |
|
- funct(CONTEXT,arg1,arg2,arg3) must be a valid expression |
|
(i.e. funct must be a function or function object) |
|
ensures |
|
- This function spawns a BSP job consisting of hosts.size()+1 processing nodes. |
|
- The processing node with a node ID of 0 will run locally on the machine |
|
calling bsp_connect(). In particular, this node will execute funct(CONTEXT,arg1,arg2,arg3), |
|
which is expected to carry out this node's portion of the BSP computation. |
|
- The other processing nodes are executed on the hosts indicated by the input |
|
argument. In particular, this function interprets hosts as a list addresses |
|
identifying machines running the bsp_listen() or bsp_listen_dynamic_port() |
|
routines. |
|
- This call to bsp_connect() blocks until the BSP computation has completed on |
|
all processing nodes. |
|
throws |
|
- dlib::socket_error |
|
This exception is thrown if there is an error which prevents the BSP |
|
job from executing. |
|
- Any exception thrown by funct() will be propagated out of this call to |
|
bsp_connect(). |
|
!*/</font> |
|
|
|
<font color='#009900'>// ---------------------------------------------------------------------------------------- |
|
</font> |
|
<font color='#0000FF'>template</font> <font color='#5555FF'><</font> |
|
<font color='#0000FF'>typename</font> funct_type, |
|
<font color='#0000FF'>typename</font> ARG1, |
|
<font color='#0000FF'>typename</font> ARG2, |
|
<font color='#0000FF'>typename</font> ARG3, |
|
<font color='#0000FF'>typename</font> ARG4 |
|
<font color='#5555FF'>></font> |
|
<font color='#0000FF'><u>void</u></font> <b><a name='bsp_connect'></a>bsp_connect</b> <font face='Lucida Console'>(</font> |
|
<font color='#0000FF'>const</font> std::vector<font color='#5555FF'><</font>network_address<font color='#5555FF'>></font><font color='#5555FF'>&</font> hosts, |
|
funct_type funct, |
|
ARG1 arg1, |
|
ARG2 arg2, |
|
ARG3 arg3, |
|
ARG4 arg4 |
|
<font face='Lucida Console'>)</font>; |
|
<font color='#009900'>/*! |
|
requires |
|
- let CONTEXT be an instance of a bsp_context object. Then: |
|
- funct(CONTEXT,arg1,arg2,arg3,arg4) must be a valid expression |
|
(i.e. funct must be a function or function object) |
|
ensures |
|
- This function spawns a BSP job consisting of hosts.size()+1 processing nodes. |
|
- The processing node with a node ID of 0 will run locally on the machine |
|
calling bsp_connect(). In particular, this node will execute funct(CONTEXT,arg1,arg2,arg3,arg4), |
|
which is expected to carry out this node's portion of the BSP computation. |
|
- The other processing nodes are executed on the hosts indicated by the input |
|
argument. In particular, this function interprets hosts as a list addresses |
|
identifying machines running the bsp_listen() or bsp_listen_dynamic_port() |
|
routines. |
|
- This call to bsp_connect() blocks until the BSP computation has completed on |
|
all processing nodes. |
|
throws |
|
- dlib::socket_error |
|
This exception is thrown if there is an error which prevents the BSP |
|
job from executing. |
|
- Any exception thrown by funct() will be propagated out of this call to |
|
bsp_connect(). |
|
!*/</font> |
|
|
|
<font color='#009900'>// ---------------------------------------------------------------------------------------- |
|
</font><font color='#009900'>// ---------------------------------------------------------------------------------------- |
|
</font> |
|
<font color='#0000FF'>template</font> <font color='#5555FF'><</font> |
|
<font color='#0000FF'>typename</font> funct_type |
|
<font color='#5555FF'>></font> |
|
<font color='#0000FF'><u>void</u></font> <b><a name='bsp_listen'></a>bsp_listen</b> <font face='Lucida Console'>(</font> |
|
<font color='#0000FF'><u>unsigned</u></font> <font color='#0000FF'><u>short</u></font> listening_port, |
|
funct_type funct |
|
<font face='Lucida Console'>)</font>; |
|
<font color='#009900'>/*! |
|
requires |
|
- listening_port != 0 |
|
- let CONTEXT be an instance of a bsp_context object. Then: |
|
- funct(CONTEXT) must be a valid expression |
|
(i.e. funct must be a function or function object) |
|
ensures |
|
- This function listens for a connection from the bsp_connect() routine. Once |
|
this connection is established, funct(CONTEXT) will be executed and it will |
|
then be able to participate in the BSP computation as one of the processing |
|
nodes. |
|
- This function will listen on TCP port listening_port for a connection from |
|
bsp_connect(). Once the connection is established, it will close the |
|
listening port so it is free for use by other applications. The connection |
|
and BSP computation will continue uninterrupted. |
|
- This call to bsp_listen() blocks until the BSP computation has completed on |
|
all processing nodes. |
|
throws |
|
- dlib::socket_error |
|
This exception is thrown if there is an error which prevents the BSP |
|
job from executing. |
|
- Any exception thrown by funct() will be propagated out of this call to |
|
bsp_connect(). |
|
!*/</font> |
|
|
|
<font color='#009900'>// ---------------------------------------------------------------------------------------- |
|
</font> |
|
<font color='#0000FF'>template</font> <font color='#5555FF'><</font> |
|
<font color='#0000FF'>typename</font> funct_type, |
|
<font color='#0000FF'>typename</font> ARG1 |
|
<font color='#5555FF'>></font> |
|
<font color='#0000FF'><u>void</u></font> <b><a name='bsp_listen'></a>bsp_listen</b> <font face='Lucida Console'>(</font> |
|
<font color='#0000FF'><u>unsigned</u></font> <font color='#0000FF'><u>short</u></font> listening_port, |
|
funct_type funct, |
|
ARG1 arg1 |
|
<font face='Lucida Console'>)</font>; |
|
<font color='#009900'>/*! |
|
requires |
|
- listening_port != 0 |
|
- let CONTEXT be an instance of a bsp_context object. Then: |
|
- funct(CONTEXT,arg1) must be a valid expression |
|
(i.e. funct must be a function or function object) |
|
ensures |
|
- This function listens for a connection from the bsp_connect() routine. Once |
|
this connection is established, funct(CONTEXT,arg1) will be executed and it will |
|
then be able to participate in the BSP computation as one of the processing |
|
nodes. |
|
- This function will listen on TCP port listening_port for a connection from |
|
bsp_connect(). Once the connection is established, it will close the |
|
listening port so it is free for use by other applications. The connection |
|
and BSP computation will continue uninterrupted. |
|
- This call to bsp_listen() blocks until the BSP computation has completed on |
|
all processing nodes. |
|
throws |
|
- dlib::socket_error |
|
This exception is thrown if there is an error which prevents the BSP |
|
job from executing. |
|
- Any exception thrown by funct() will be propagated out of this call to |
|
bsp_connect(). |
|
!*/</font> |
|
|
|
<font color='#009900'>// ---------------------------------------------------------------------------------------- |
|
</font> |
|
<font color='#0000FF'>template</font> <font color='#5555FF'><</font> |
|
<font color='#0000FF'>typename</font> funct_type, |
|
<font color='#0000FF'>typename</font> ARG1, |
|
<font color='#0000FF'>typename</font> ARG2 |
|
<font color='#5555FF'>></font> |
|
<font color='#0000FF'><u>void</u></font> <b><a name='bsp_listen'></a>bsp_listen</b> <font face='Lucida Console'>(</font> |
|
<font color='#0000FF'><u>unsigned</u></font> <font color='#0000FF'><u>short</u></font> listening_port, |
|
funct_type funct, |
|
ARG1 arg1, |
|
ARG2 arg2 |
|
<font face='Lucida Console'>)</font>; |
|
<font color='#009900'>/*! |
|
requires |
|
- listening_port != 0 |
|
- let CONTEXT be an instance of a bsp_context object. Then: |
|
- funct(CONTEXT,arg1,arg2) must be a valid expression |
|
(i.e. funct must be a function or function object) |
|
ensures |
|
- This function listens for a connection from the bsp_connect() routine. Once |
|
this connection is established, funct(CONTEXT,arg1,arg2) will be executed and |
|
it will then be able to participate in the BSP computation as one of the |
|
processing nodes. |
|
- This function will listen on TCP port listening_port for a connection from |
|
bsp_connect(). Once the connection is established, it will close the |
|
listening port so it is free for use by other applications. The connection |
|
and BSP computation will continue uninterrupted. |
|
- This call to bsp_listen() blocks until the BSP computation has completed on |
|
all processing nodes. |
|
throws |
|
- dlib::socket_error |
|
This exception is thrown if there is an error which prevents the BSP |
|
job from executing. |
|
- Any exception thrown by funct() will be propagated out of this call to |
|
bsp_connect(). |
|
!*/</font> |
|
|
|
<font color='#009900'>// ---------------------------------------------------------------------------------------- |
|
</font> |
|
<font color='#0000FF'>template</font> <font color='#5555FF'><</font> |
|
<font color='#0000FF'>typename</font> funct_type, |
|
<font color='#0000FF'>typename</font> ARG1, |
|
<font color='#0000FF'>typename</font> ARG2, |
|
<font color='#0000FF'>typename</font> ARG3 |
|
<font color='#5555FF'>></font> |
|
<font color='#0000FF'><u>void</u></font> <b><a name='bsp_listen'></a>bsp_listen</b> <font face='Lucida Console'>(</font> |
|
<font color='#0000FF'><u>unsigned</u></font> <font color='#0000FF'><u>short</u></font> listening_port, |
|
funct_type funct, |
|
ARG1 arg1, |
|
ARG2 arg2, |
|
ARG3 arg3 |
|
<font face='Lucida Console'>)</font>; |
|
<font color='#009900'>/*! |
|
requires |
|
- listening_port != 0 |
|
- let CONTEXT be an instance of a bsp_context object. Then: |
|
- funct(CONTEXT,arg1,arg2,arg3) must be a valid expression |
|
(i.e. funct must be a function or function object) |
|
ensures |
|
- This function listens for a connection from the bsp_connect() routine. Once |
|
this connection is established, funct(CONTEXT,arg1,arg2,arg3) will be |
|
executed and it will then be able to participate in the BSP computation as |
|
one of the processing nodes. |
|
- This function will listen on TCP port listening_port for a connection from |
|
bsp_connect(). Once the connection is established, it will close the |
|
listening port so it is free for use by other applications. The connection |
|
and BSP computation will continue uninterrupted. |
|
- This call to bsp_listen() blocks until the BSP computation has completed on |
|
all processing nodes. |
|
throws |
|
- dlib::socket_error |
|
This exception is thrown if there is an error which prevents the BSP |
|
job from executing. |
|
- Any exception thrown by funct() will be propagated out of this call to |
|
bsp_connect(). |
|
!*/</font> |
|
|
|
<font color='#009900'>// ---------------------------------------------------------------------------------------- |
|
</font> |
|
<font color='#0000FF'>template</font> <font color='#5555FF'><</font> |
|
<font color='#0000FF'>typename</font> funct_type, |
|
<font color='#0000FF'>typename</font> ARG1, |
|
<font color='#0000FF'>typename</font> ARG2, |
|
<font color='#0000FF'>typename</font> ARG3, |
|
<font color='#0000FF'>typename</font> ARG4 |
|
<font color='#5555FF'>></font> |
|
<font color='#0000FF'><u>void</u></font> <b><a name='bsp_listen'></a>bsp_listen</b> <font face='Lucida Console'>(</font> |
|
<font color='#0000FF'><u>unsigned</u></font> <font color='#0000FF'><u>short</u></font> listening_port, |
|
funct_type funct, |
|
ARG1 arg1, |
|
ARG2 arg2, |
|
ARG3 arg3, |
|
ARG4 arg4 |
|
<font face='Lucida Console'>)</font>; |
|
<font color='#009900'>/*! |
|
requires |
|
- listening_port != 0 |
|
- let CONTEXT be an instance of a bsp_context object. Then: |
|
- funct(CONTEXT,arg1,arg2,arg3,arg4) must be a valid expression |
|
(i.e. funct must be a function or function object) |
|
ensures |
|
- This function listens for a connection from the bsp_connect() routine. Once |
|
this connection is established, funct(CONTEXT,arg1,arg2,arg3,arg4) will be |
|
executed and it will then be able to participate in the BSP computation as |
|
one of the processing nodes. |
|
- This function will listen on TCP port listening_port for a connection from |
|
bsp_connect(). Once the connection is established, it will close the |
|
listening port so it is free for use by other applications. The connection |
|
and BSP computation will continue uninterrupted. |
|
- This call to bsp_listen() blocks until the BSP computation has completed on |
|
all processing nodes. |
|
throws |
|
- dlib::socket_error |
|
This exception is thrown if there is an error which prevents the BSP |
|
job from executing. |
|
- Any exception thrown by funct() will be propagated out of this call to |
|
bsp_connect(). |
|
!*/</font> |
|
|
|
<font color='#009900'>// ---------------------------------------------------------------------------------------- |
|
</font><font color='#009900'>// ---------------------------------------------------------------------------------------- |
|
</font> |
|
<font color='#0000FF'>template</font> <font color='#5555FF'><</font> |
|
<font color='#0000FF'>typename</font> port_notify_function_type, |
|
<font color='#0000FF'>typename</font> funct_type |
|
<font color='#5555FF'>></font> |
|
<font color='#0000FF'><u>void</u></font> <b><a name='bsp_listen_dynamic_port'></a>bsp_listen_dynamic_port</b> <font face='Lucida Console'>(</font> |
|
<font color='#0000FF'><u>unsigned</u></font> <font color='#0000FF'><u>short</u></font> listening_port, |
|
port_notify_function_type port_notify_function, |
|
funct_type funct |
|
<font face='Lucida Console'>)</font>; |
|
<font color='#009900'>/*! |
|
requires |
|
- let CONTEXT be an instance of a bsp_context object. Then: |
|
- funct(CONTEXT) must be a valid expression |
|
(i.e. funct must be a function or function object) |
|
- port_notify_function((unsigned short) 1234) must be a valid expression |
|
(i.e. port_notify_function() must be a function or function object taking an |
|
unsigned short) |
|
ensures |
|
- This function listens for a connection from the bsp_connect() routine. Once |
|
this connection is established, funct(CONTEXT) will be executed and it will |
|
then be able to participate in the BSP computation as one of the processing |
|
nodes. |
|
- if (listening_port != 0) then |
|
- This function will listen on TCP port listening_port for a connection |
|
from bsp_connect(). |
|
- else |
|
- An available TCP port number is automatically selected and this function |
|
will listen on it for a connection from bsp_connect(). |
|
- Once a listening port is opened, port_notify_function() is called with the |
|
port number used. This provides a mechanism to find out what listening port |
|
has been used if it is automatically selected. It also allows you to find |
|
out when the routine has begun listening for an incoming connection from |
|
bsp_connect(). |
|
- Once a connection is established, we will close the listening port so it is |
|
free for use by other applications. The connection and BSP computation will |
|
continue uninterrupted. |
|
- This call to bsp_listen_dynamic_port() blocks until the BSP computation has |
|
completed on all processing nodes. |
|
throws |
|
- dlib::socket_error |
|
This exception is thrown if there is an error which prevents the BSP |
|
job from executing. |
|
- Any exception thrown by funct() will be propagated out of this call to |
|
bsp_connect(). |
|
!*/</font> |
|
|
|
<font color='#009900'>// ---------------------------------------------------------------------------------------- |
|
</font> |
|
<font color='#0000FF'>template</font> <font color='#5555FF'><</font> |
|
<font color='#0000FF'>typename</font> port_notify_function_type, |
|
<font color='#0000FF'>typename</font> funct_type, |
|
<font color='#0000FF'>typename</font> ARG1 |
|
<font color='#5555FF'>></font> |
|
<font color='#0000FF'><u>void</u></font> <b><a name='bsp_listen_dynamic_port'></a>bsp_listen_dynamic_port</b> <font face='Lucida Console'>(</font> |
|
<font color='#0000FF'><u>unsigned</u></font> <font color='#0000FF'><u>short</u></font> listening_port, |
|
port_notify_function_type port_notify_function, |
|
funct_type funct, |
|
ARG1 arg1 |
|
<font face='Lucida Console'>)</font>; |
|
<font color='#009900'>/*! |
|
requires |
|
- let CONTEXT be an instance of a bsp_context object. Then: |
|
- funct(CONTEXT,arg1) must be a valid expression |
|
(i.e. funct must be a function or function object) |
|
- port_notify_function((unsigned short) 1234) must be a valid expression |
|
(i.e. port_notify_function() must be a function or function object taking an |
|
unsigned short) |
|
ensures |
|
- This function listens for a connection from the bsp_connect() routine. Once |
|
this connection is established, funct(CONTEXT,arg1) will be executed and it |
|
will then be able to participate in the BSP computation as one of the |
|
processing nodes. |
|
- if (listening_port != 0) then |
|
- This function will listen on TCP port listening_port for a connection |
|
from bsp_connect(). |
|
- else |
|
- An available TCP port number is automatically selected and this function |
|
will listen on it for a connection from bsp_connect(). |
|
- Once a listening port is opened, port_notify_function() is called with the |
|
port number used. This provides a mechanism to find out what listening port |
|
has been used if it is automatically selected. It also allows you to find |
|
out when the routine has begun listening for an incoming connection from |
|
bsp_connect(). |
|
- Once a connection is established, we will close the listening port so it is |
|
free for use by other applications. The connection and BSP computation will |
|
continue uninterrupted. |
|
- This call to bsp_listen_dynamic_port() blocks until the BSP computation has |
|
completed on all processing nodes. |
|
throws |
|
- dlib::socket_error |
|
This exception is thrown if there is an error which prevents the BSP |
|
job from executing. |
|
- Any exception thrown by funct() will be propagated out of this call to |
|
bsp_connect(). |
|
!*/</font> |
|
|
|
<font color='#009900'>// ---------------------------------------------------------------------------------------- |
|
</font> |
|
<font color='#0000FF'>template</font> <font color='#5555FF'><</font> |
|
<font color='#0000FF'>typename</font> port_notify_function_type, |
|
<font color='#0000FF'>typename</font> funct_type, |
|
<font color='#0000FF'>typename</font> ARG1, |
|
<font color='#0000FF'>typename</font> ARG2 |
|
<font color='#5555FF'>></font> |
|
<font color='#0000FF'><u>void</u></font> <b><a name='bsp_listen_dynamic_port'></a>bsp_listen_dynamic_port</b> <font face='Lucida Console'>(</font> |
|
<font color='#0000FF'><u>unsigned</u></font> <font color='#0000FF'><u>short</u></font> listening_port, |
|
port_notify_function_type port_notify_function, |
|
funct_type funct, |
|
ARG1 arg1, |
|
ARG2 arg2 |
|
<font face='Lucida Console'>)</font>; |
|
<font color='#009900'>/*! |
|
requires |
|
- let CONTEXT be an instance of a bsp_context object. Then: |
|
- funct(CONTEXT,arg1,arg2) must be a valid expression |
|
(i.e. funct must be a function or function object) |
|
- port_notify_function((unsigned short) 1234) must be a valid expression |
|
(i.e. port_notify_function() must be a function or function object taking an |
|
unsigned short) |
|
ensures |
|
- This function listens for a connection from the bsp_connect() routine. Once |
|
this connection is established, funct(CONTEXT,arg1,arg2) will be executed and |
|
it will then be able to participate in the BSP computation as one of the |
|
processing nodes. |
|
- if (listening_port != 0) then |
|
- This function will listen on TCP port listening_port for a connection |
|
from bsp_connect(). |
|
- else |
|
- An available TCP port number is automatically selected and this function |
|
will listen on it for a connection from bsp_connect(). |
|
- Once a listening port is opened, port_notify_function() is called with the |
|
port number used. This provides a mechanism to find out what listening port |
|
has been used if it is automatically selected. It also allows you to find |
|
out when the routine has begun listening for an incoming connection from |
|
bsp_connect(). |
|
- Once a connection is established, we will close the listening port so it is |
|
free for use by other applications. The connection and BSP computation will |
|
continue uninterrupted. |
|
- This call to bsp_listen_dynamic_port() blocks until the BSP computation has |
|
completed on all processing nodes. |
|
throws |
|
- dlib::socket_error |
|
This exception is thrown if there is an error which prevents the BSP |
|
job from executing. |
|
- Any exception thrown by funct() will be propagated out of this call to |
|
bsp_connect(). |
|
!*/</font> |
|
|
|
<font color='#009900'>// ---------------------------------------------------------------------------------------- |
|
</font> |
|
<font color='#0000FF'>template</font> <font color='#5555FF'><</font> |
|
<font color='#0000FF'>typename</font> port_notify_function_type, |
|
<font color='#0000FF'>typename</font> funct_type, |
|
<font color='#0000FF'>typename</font> ARG1, |
|
<font color='#0000FF'>typename</font> ARG2, |
|
<font color='#0000FF'>typename</font> ARG3 |
|
<font color='#5555FF'>></font> |
|
<font color='#0000FF'><u>void</u></font> <b><a name='bsp_listen_dynamic_port'></a>bsp_listen_dynamic_port</b> <font face='Lucida Console'>(</font> |
|
<font color='#0000FF'><u>unsigned</u></font> <font color='#0000FF'><u>short</u></font> listening_port, |
|
port_notify_function_type port_notify_function, |
|
funct_type funct, |
|
ARG1 arg1, |
|
ARG2 arg2, |
|
ARG3 arg3 |
|
<font face='Lucida Console'>)</font>; |
|
<font color='#009900'>/*! |
|
requires |
|
- let CONTEXT be an instance of a bsp_context object. Then: |
|
- funct(CONTEXT,arg1,arg2,arg3) must be a valid expression |
|
(i.e. funct must be a function or function object) |
|
- port_notify_function((unsigned short) 1234) must be a valid expression |
|
(i.e. port_notify_function() must be a function or function object taking an |
|
unsigned short) |
|
ensures |
|
- This function listens for a connection from the bsp_connect() routine. Once |
|
this connection is established, funct(CONTEXT,arg1,arg2,arg3) will be |
|
executed and it will then be able to participate in the BSP computation as |
|
one of the processing nodes. |
|
- if (listening_port != 0) then |
|
- This function will listen on TCP port listening_port for a connection |
|
from bsp_connect(). |
|
- else |
|
- An available TCP port number is automatically selected and this function |
|
will listen on it for a connection from bsp_connect(). |
|
- Once a listening port is opened, port_notify_function() is called with the |
|
port number used. This provides a mechanism to find out what listening port |
|
has been used if it is automatically selected. It also allows you to find |
|
out when the routine has begun listening for an incoming connection from |
|
bsp_connect(). |
|
- Once a connection is established, we will close the listening port so it is |
|
free for use by other applications. The connection and BSP computation will |
|
continue uninterrupted. |
|
- This call to bsp_listen_dynamic_port() blocks until the BSP computation has |
|
completed on all processing nodes. |
|
throws |
|
- dlib::socket_error |
|
This exception is thrown if there is an error which prevents the BSP |
|
job from executing. |
|
- Any exception thrown by funct() will be propagated out of this call to |
|
bsp_connect(). |
|
!*/</font> |
|
|
|
<font color='#009900'>// ---------------------------------------------------------------------------------------- |
|
</font> |
|
<font color='#0000FF'>template</font> <font color='#5555FF'><</font> |
|
<font color='#0000FF'>typename</font> port_notify_function_type, |
|
<font color='#0000FF'>typename</font> funct_type, |
|
<font color='#0000FF'>typename</font> ARG1, |
|
<font color='#0000FF'>typename</font> ARG2, |
|
<font color='#0000FF'>typename</font> ARG3, |
|
<font color='#0000FF'>typename</font> ARG4 |
|
<font color='#5555FF'>></font> |
|
<font color='#0000FF'><u>void</u></font> <b><a name='bsp_listen_dynamic_port'></a>bsp_listen_dynamic_port</b> <font face='Lucida Console'>(</font> |
|
<font color='#0000FF'><u>unsigned</u></font> <font color='#0000FF'><u>short</u></font> listening_port, |
|
port_notify_function_type port_notify_function, |
|
funct_type funct, |
|
ARG1 arg1, |
|
ARG2 arg2, |
|
ARG3 arg3, |
|
ARG4 arg4 |
|
<font face='Lucida Console'>)</font>; |
|
<font color='#009900'>/*! |
|
requires |
|
- let CONTEXT be an instance of a bsp_context object. Then: |
|
- funct(CONTEXT,arg1,arg2,arg3,arg4) must be a valid expression |
|
(i.e. funct must be a function or function object) |
|
- port_notify_function((unsigned short) 1234) must be a valid expression |
|
(i.e. port_notify_function() must be a function or function object taking an |
|
unsigned short) |
|
ensures |
|
- This function listens for a connection from the bsp_connect() routine. Once |
|
this connection is established, funct(CONTEXT,arg1,arg2,arg3,arg4) will be |
|
executed and it will then be able to participate in the BSP computation as |
|
one of the processing nodes. |
|
- if (listening_port != 0) then |
|
- This function will listen on TCP port listening_port for a connection |
|
from bsp_connect(). |
|
- else |
|
- An available TCP port number is automatically selected and this function |
|
will listen on it for a connection from bsp_connect(). |
|
- Once a listening port is opened, port_notify_function() is called with the |
|
port number used. This provides a mechanism to find out what listening port |
|
has been used if it is automatically selected. It also allows you to find |
|
out when the routine has begun listening for an incoming connection from |
|
bsp_connect(). |
|
- Once a connection is established, we will close the listening port so it is |
|
free for use by other applications. The connection and BSP computation will |
|
continue uninterrupted. |
|
- This call to bsp_listen_dynamic_port() blocks until the BSP computation has |
|
completed on all processing nodes. |
|
throws |
|
- dlib::socket_error |
|
This exception is thrown if there is an error which prevents the BSP |
|
job from executing. |
|
- Any exception thrown by funct() will be propagated out of this call to |
|
bsp_connect(). |
|
!*/</font> |
|
|
|
<font color='#009900'>// ---------------------------------------------------------------------------------------- |
|
</font><font color='#009900'>// ---------------------------------------------------------------------------------------- |
|
</font> |
|
<b>}</b> |
|
|
|
<font color='#0000FF'>#endif</font> <font color='#009900'>// DLIB_BsP_ABSTRACT_Hh_ |
|
</font> |
|
|
|
</pre></body></html> |
