C syntax:
void phish_exit() void phish_close(int iport)
C examples:
#include "phish.h" phish_exit(); phish_close(0);
C++ syntax:
void exit() void close(int iport)
C++ examples:
#include "phish.hpp" phish::exit(); phish::close(0);
Python syntax:
def exit() def close(iport)
Python examples:
import phish phish.exit(); phish.close(0);
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 serve to shutdown a running minnow, either entirely or a portion of its output capabilities. They trigger the closing of a minnow's output port(s) which notifies downstream minnows, so they also can clean-up and exit.
See this section of the Minnows doc page for a discussion of shutdown options for PHISH programs.
The phish_exit() function is the most commonly used mechanism for performing an orderly shutdown of a PHISH program. Once called, no further calls to the PHISH library can be made by a minnow, so it is often the final line of a minnow program.
When phish_exit() is called it performs the following operations:
The stats message is printed with the same supplementary information as the phish_error function, to identify the minnow that printed it.
Closing a minnow's output port involves sending a "done" message to each minnow (in each set of minnows) connected as a receiver to that port, so that they know to expect no more datums from this minnow.
When all the minnows in a set have invoked phish_exit() to close an output port, each downstream minnow that receives output from this port will have received a series of "done" messages on its corresponding input port. Each minnow keeps a count of the total # of minnows that send to that port, so it will know when the requisite number of done messages have been received to close the input port.
In the MPI version of the library, the final step is to invoke MPI_Finalize(), which means no further MPI calls can be made by the minnow.
In the ZMQ version of the library, the final step is to close any open ZMQ context(s), so no further ZMQ calls can be made by the minnow.
Note that this function is often called directly by the most upstream minnow(s) in a PHISH school, when they are done with their task (e.g. reading data from a file).
Other downstream minnows often call phish_exit() after the phish_loop or phish_probe function returns control to the minnow, since that only occurs when all the minnow's input ports have been closed. In this manner, the shutdown procedure cascades from minnow to minnow.
The phish_close() function is used less often than the phish_exit() function. It can be useful when some minnow in the middle of a data processing pipeline needs to trigger an orderly shutdown of the PHISH program.
Phish_close() closes the specified iport output port of a minnow. This procedure involves sending a "done" message to each minnow (in each set of minnows) connected as a receiver to that port, so that they know to expect no more datums from this minnow.
When all the minnows in a set have invoked phish_close() on an output port, each downstream minnow that receives output from this port will have received a series of "done" messages on its corresponding input port. Each minnow keeps a count of the total # of minnows that send to that port, so it will know when the requisite number of done messages have been received to close the input port. As input ports are closed, this typically triggers the minnow to invoke phish_exit() or phish_close(). In this manner, the shutdown procedure cascades from minnow to minnow.
This function does nothing if the specified output port is already closed.
Restrictions: none
Related commands: