org.jcsp.lang
Interface Poisonable

All Known Subinterfaces:

ChannelInput, ChannelInputInt, ChannelOutput, ChannelOutputInt, FilteredChannelInput, FilteredChannelOutput, FilteredSharedChannelInput, FilteredSharedChannelOutput, MigratableChannelInput, MigratableChannelOutput, NetChannelInput, NetChannelOutput, NetSharedChannelInput, NetSharedChannelOutput, RejectableChannelInput, RejectableChannelOutput, SharedChannelInput, SharedChannelInputInt, SharedChannelOutput, SharedChannelOutputInt

All Known Implementing Classes:

AltingChannelInput, AltingChannelInputInt, AltingChannelInputWrapper, AltingChannelOutput, AltingChannelOutputInt, BlackHoleChannel, BlackHoleChannelInt, ChannelInputWrapper, ChannelOutputWrapper, FilteredAltingChannelInput, FilteredSharedChannelInputWrapper, FilteredSharedChannelOutputWrapper, MigratableAltingChannelInput, NetAltingChannelInput, RejectableAltingChannelInput

public interface Poisonable

All channel-ends implement this inteface.

Channels are immune to poisoning unless explicitly constructed to be poisonable (by those static methods in Channel that prescribe a level of immunity – e.g. this one).

Poisonable channels are immune to poisons with strength below the level of immunity given when they were constructed. Above this level, the poison will take effect.

Any attempt to use a poisoned channel will cause a PoisonException to be thrown. Processes blocked on a channel that gets poisoned will be awoken with a thrown PoisonException.

Poisoning is an effective technique for the safe interruption of processes and termination of process networks or sub-networks (of any connected topology). Note that poisoning a channel is non-blocking. Also, poisoning an already poisoned channel does no (extra) harm.

The algorithm is simple. One or more processes may independently decide to poison their environment and terminate. To do this, they poison their external channels, tidy up and die. Any process accessing or waiting on a poisoned channel gets a PoisonException thrown: this should be caught, local affairs settled and external channels posioned before the process terminates. That's all.

An example is shown in Generate and here, where the channels in the example network are constructed to be poisonable (with an immunity of zero) and FairMuxTime initiates the shut-down (by injecting poison of strength 42).

To bring down only a sub-network, the internal channels of the subnet should have an immunity lower than its external channels. One of the subnet processes must choose (or be told) to release poison with strength one greater than the subnet channel immunity. That will terminate just the subnet, leaving the surrounding processes unaffected – until they next try to communicate with the shut-down subnet. This is no problem so long as the subnet is being replaced, which is the usual reason for closing the previous one.

See Also:

PoisonException

Method Summary

void	poison(int strength) This injects poison into the channel.

Method Detail

poison

void poison(int strength)

This injects poison into the channel. If the channel was not explicitly constructed to be poisonable or if the strength of poison is not greater than the channel immunity level, the poison will have no effect.

Parameters:

strength - the strength of the poison (must be >= 0).