C syntax:
void phish_loop() void phish_probe(void (*probefunc)()) int phish_recv()
C examples:
#include "phish.h" phish_loop(); phish_probe(count); int n = phish_recv();
C++ syntax:
void loop() void probe(void (*probefunc)()) int recv()
C++ examples:
#include "phish.hpp" phish::loop(); phish::probe(count); int n = phish::recv();
Python syntax:
def loop() def probe(probefunc) def recv()
Python examples:
import phish phish.loop() phish.probe(count) n = phish.recv()
Description:
These are PHISH library functions which can be called from a minnow application. In PHISH lingo, a "minnow" is a stand-alone application which makes calls to the PHISH library.
These functions are used to receive datums sent by other minnows.
All received datums arrive on input ports the minnow defines and which the PHISH input script uses to route datums from one set of minnows to another set.
The functions documented on this page receive the next datum, whichever input port it arrives on. It is up to the minnow to take the appropriate port-specific action if necessary. This can be done by defining a port-specific callback function via the phish_input function. Or by querying what port the datum was received on via the phish_datum function.
Note that datums sent by a minnow to itself are always processed first by all of these functions. For datums sent from another minnow, they are processed in the order they are received, i.e. first-come, first-served.
The phish_loop() function turns control over to the PHISH library. It will wait for the next datum to arrive on any input port. When it does one of three things happen:
(1) For a regular datum, phish_loop() will make a callback to the minnow, to the datum callback function assigned to the input port the datum was received on. See the phish_input function for how this callback function is assigned. When the callback function returns, control is returned to phish_loop().
(2) For a datum that signals the closure of an input port, phish_loop() will make a callback to the minnow, to the done callback function assigned to the input port the datum was received on. See the phish_input function for how this callback function is assigned. When the callback function returns, control is returned to phish_loop().
(3) For a datum that closes the last open input port, step (2) is performed, and then an additional callback to the minnow is made, to the alldone callback function (optionally) assigned by the phish_callback function. When the callback function returns, control is returned to phish_loop().
After option (3) has occurred, phish_loop() returns, giving control back to the minnow. Typically, the minnow will then clean up and call phish_exit, since all its input ports are closed and no more datums can be received.
The phish_probe() function is identical to phish_loop(), except that instead of waiting for the next datum to arrive, phish_probe() checks if a datum has arrived. If not, then it immediately calls the specified probefunc callback function. This allows the minnow to do useful work while waiting for the next datum to arrive.
The probefunc function should have the following form:
void probefunc() { }
or
def probefunc()
in Python,
where "probefunc" is replaced by a function name of your choice. When the probefunc callback function returns, control is returned to phish_probe().
Note that just like phish_loop(), phish_probe() will not return control to the minnow, until option (3) above has occured, i.e. all input ports have been closed.
The phish_recv() function allows the minnow to request datums explicitly, rather than be handing control to phish_loop() or phish_probe() and being called back to by those functions.
The phish_recv() function checks if a datum has arrived and returns regardless. It returns a value of 0 if no datum is available. It returns a value N > 0 if a datum has arrived, with N = the number of fields in the datum. See the phish_unpack and phish_datum doc pages for info on how the received datum can be further processed.
If a datum is received that signals the closure of an input port, then phish_recv() will perform the same options (2) and (3) listed above, making callbacks to the done callback function and alldone callback function as appopriate, and then return with a value of -1.
Restrictions:
These functions can only be called after phish_check has been called.
Related commands: