Syntax:
hook sendID:outport style recvID:inport
Examples:
hook 1 single 2 hook 2:1 hashed 2:1
Description:
Hook is a command that can be used in a PHISH input script which is recognized by the bait.py setup program. It determines how the output from a minnow in one school is routed to the input of a minnow in another school when the PHISH program is run. In PHISH lingo, a "minnow" is a stand-alone application which makes calls to the PHISH library to exchange data with other PHISH minnows.
The topology of communication patterns between minnows defined by a series of hook commands defines how multiple schools of minnows are harnessed together to perform a desired computational task. It also defins how parallelism is exploited by the schools of minnows.
A hook is made between two schools of minnows, one school sends datums, the other set receives them. Each school may contain one or more minnows, as defined by the school command. Since a datum is typically sent from a single minnow to a single receiving minnow, the style of the hook determines which minnow in the sending schoold communicates with which minnow in the receiving school.
Each minnow can send datums through specific output ports. If a minnow defines N output ports, then they are numbered 0 to N-1. Likewise a minnow can receive data through specific input ports. If a minnow defines M input ports, then they are numbered 0 to M-1. Ports enable a minnow to have multiple input and output hooks, and for a PHISH input script to hook a single set of minnows to multiple other sets of minnows with different communication patterns. For example, a stream of data might be processed by a minnow, reading from its input port 0, and writing to its output port 0. But the minnow might also look for incoming datums on its input port 1, that signify some kind of external message from a "control" minnow triggered by the user, e.g. asking the minnow to print out its current statistics. See the Minnows doc page for more information about how minnows can define and use ports.
The specified sendID and outport are the minnows which will send datums through their output port outport. If outport is not specified with a colon following the sendID, then a default output port of 0 is assumed.
The specified recvID and inport are the minnows which will receive the sent datums through their input port inport. If inport is not specified with a colon following the recvID, then a default input port of 0 is assumed.
Both sendID and recvID must be the IDs of minnows previously defined by a minnow command.
Note that there can be multiple hook commands which hook the same sendID and same (or different) outport to different recvID:inport minnows. Likewise, there can be multiple hook commands which hook the same recvID and same (or different) inport to different sendID:outport minnows. There can even be multiple hook commands which hook the same sendID and same (or different) outport to the same recvID:inport minnows.
Also note that for all of the styles (except as noted below), the sendID and recvID can be the same, meaning a set of minnows will send datums to themselves.
These are the different hook styles supported by the hook command.
The single style hooks N sending minnows to one receiving minnow. N = 1 is allowed. All the sending minnows send their datums to a single receiving minnow.
The paired style hooks N sending minnows to N receiving minnows. N = 1 is allowed. Each of the N sending minnows sends it datums to a specific partner receiving minnow.
The hashed style hooks N sending minnows to M receiving minnows. N does not have to equal M, and either or both of N, M = 1 is allowed. When any of the N minnows sends a datum, it must also define a value for the PHISH library to hash on, which will determine which of the M receiving minnows it is sent to. See the doc page for the phish_send_hashed() library function for more explanation of how this is done.
The roundrobin style hooks N sending minnows to M receiving minnows. N does not have to equal M, and either or both of N, M = 1 is allowed. Each of the N senders cycles through the list of M receivers each time it sends a datum, in a roundrobin fashion. a different. If the receivers are numbered 0 to M-1, a sender will send its first datum to 0, its 2nd to 1, its Mth to M-1, its M+1 datum to 0, etc.
The direct style hooks N sending minnows to M receiving minnows. N does not have to equal M, and either or both of N, M = 1 is allowed. When any of the N minnows sends a datum, it must also choosed a specific one of the M receiving minnows to send to. See the doc page for the phish_send_direct() library function for more explanation of how this is done.
The bcast style hooks N sending minnows to M receiving minnows. N does not have to equal M, and either or both of N, M = 1 is allowed. When any of the N minnows sends a datum, it sends a copy of it once to each of the M receiving minnows.
The chain style configures N minnows as a 1-dimensional chain so that each minnow sends datums to the next minnow in the chain, and likewise each minnow receives datums from the previous minnow in the chain. The first minnow in the chain cannot receive, and the last minnow in the chain cannot send. N > 1 is required. The sendID must also be the same as the recvID, since the same set of minnows is sending and receiving.
The ring style is the same as the chain style, except that the N minnows are configured as a 1-dimensional loop. Each minnow sends datums to the next minnow in the loop, and likewise each minnow receives datums from the previous minnow in the loop. This includes the first and last minnows. N > 1 is required. The sendID must also be the same as the recvID, since the same set of minnows is sending and receiving.
The following hook styles will be supported in future versions of PHISH:
The publish and subscribe styles are different in that they do not hook two sets of minnows to each other. Instead they hook one set of minnows to an external socket, either for writing or reading datums. The external socket will typically be driven by some external program which is either reading from the socket or writing to it, but the running PHISH program requires no knowledge of that program. It could be another PHISH program or some completely different program.
The publish style hooks N sending minnows to a socket. N = 1 is allowed. The recvID:inport argument is replaced with a TCP port #, which is an integer, e.g. 25. When each minnow sends a datum it will "publish" the bytes of the datum to that TCP port, on the machine the minnow is running on. In socket lingo, "publishing" means that the sender has no communication with any processes which may be reading from the socket. The sender simply writes the bytes and continues without blocking. If no process is reading from the socket, the datum is lost.
The subscribe style hooks M receiving minnows to a socket. M = 1 is allowed. The sendID:outport argument is replaced with a hostname and TCP port #, separated by a colon, e.g. www.foo.com:25. Each minnow receives datums by "subscribing" to the TCP port on the specified host. In socket lingo, "subscribing" means that the receiver has no communication with any process which is writing to the socket. The receiver simply checks if a datum is available and reads it. If a new datum arrives before the receiver is ready to read it, the datum is lost.
Note that multiple processes can publish to the same physical socket, and likewise multiple processes can subscribe to the same physical socket. In the latter case, each receiving process reads the same published datum.
Restrictions:
The publish and subscribe styles have not been implemented yet by any of the PHISH library versions.
Related commands:
Default: none