Package org.jcsp.lang

# Interface Poisonable

All Known Subinterfaces:
  `ChannelInput`, `ChannelInputInt`, `ChannelOutput`, `ChannelOutputInt`, `FilteredChannelInput`, `FilteredChannelOutput`, `FilteredSharedChannelInput`, `FilteredSharedChannelOutput`, `SharedChannelInput`, `SharedChannelInputInt`, `SharedChannelOutput`, `SharedChannelOutputInt`

All Known Implementing Classes:
  `AltingChannelInput`, `AltingChannelInputInt`, `AltingChannelInputWrapper`, `AltingChannelOutput`, `AltingChannelOutputInt`, `BlackHoleChannel`, `BlackHoleChannelInt`, `ChannelInputWrapper`, `ChannelOutputWrapper`, `FilteredAltingChannelInput`, `FilteredSharedChannelInputWrapper`, `FilteredSharedChannelOutputWrapper`

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

Modifier and Type
Method
Description
`void`
`poison(int strength)`
This injects poison into the channel.

## Method Details

### 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).