Shutting down such process networks would be a difficult problem if you tried to send special shutdown messages down the channels; not only would the type of the channels probably need to be altered, but trying to make sure the shutdown message travels in the right way around the network (such as to avoid deadlock) is often difficult.
Poison solves this problem. Channels can be poisoned by either the reading or the writing end of a channel. Once poisoned, a channel remains poisoned forever; there is no cure for poison. Any attempt to communicate over a poisoned channel (an output, an input or an extended input) will result in a PoisonException being thrown. The pending() and inputGuard() methods of AltChanin will not cause a PoisonException to be thrown. The guard for a poisoned channel is always ready.
The expected course of action for a process upon catching a PoisonException is for it to poison all its available channel-ends and then finish cleanly (closing any files, resigning from any barriers, etc). In this way, poisoning one channel should eventually lead to the entire channel network being poisoned, and all the processes finishing cleanly.
Poisoning unbuffered channels always takes effect immediately, from either end. Poisoning a buffered channel from a reading end (Chanin or AltChanin) is always noticed by the writing end (Chanout) immediately. However, poisoning by a writing end will not be noticed by the reading end until the buffer is empty. So if a buffered channel has three items of data in the buffer, and the writer poisons the channel, the reader will not have a PoisonException thrown until it has read the three items successfully. When it attempts the fourth read, the PoisonException will be thrown.
This buffered-poison behaviour may seem odd at first, but otherwise a writer could write some final items of data to a channel and then want to poison it to signify that it has finished. It would not want to poison the channel until the reader had taken all the items of data, but without an acknowledgement channel or somesuch, it would not know when that was. So instead, under the current scheme, a writer can write the items and immediately poison the channel, safe in the knowledge that the reader will not perceive the poison until it has emptied the buffer.
More information is available in the Poison section of the guide.
Classes | |
| class | csp::PoisonException |
| The poison exception. More... | |
1.4.7