Permit

Permit provides a way of requesting control of a game object resource such as a Track or Junction.

Permits are acquired by requesting them from various game objects. Some objects may only give out one permit at a time, others may give multiple permits with certain conditions. For example, a track could permit several trains travelling in the same direction.

Permits are used to stop scripts from 'fighting' over resources in situations such as:

- Two trains want to go opposite directions down a single line; or
- Two trains want to go through the same junction.

When a request is made, a permit is always returned, however it is not automatically granted. Instead, you have to wait for the permit to reach a 'granted' state. You can determine when a permit has been granted by:

- Performing a <l gscLangKeyWait wait()> on a message of type (<m"Permit">, <m "Granted">).
   Just make sure you check that it is <bi YOUR> permit that was granted. You can do this by
   just calling WasGranted() on your permit after receiving the message. The message is sent
   to the GameObject passed in to the <b RequestPermit> methods such as
   Junction::RequestPermit() or Track::RequestPermitForTrain().

- Regularly checking IsGranted() which will return true after the Permit is Granted.
   DO NOT use IsGranted() continuously to wait because it just wastes CPU time, but there
   may be other uses for this method, such as if we want to request a permit now for use in the
   future, and don't want to have to listen to the (<m"Permit">, <m "Granted">) message all the
   time.

Permits are released automatically. When no more references to a particular Permit remain, it is automatically released. So you generally don't need to call Release().

Permits can be in one of three states:

- \ref permitStates "REQUESTING"
- \ref permitStates "GRANTED"
- \ref permitStates "RELEASED"

A permit is initially in the \ref permitStates "REQUESTING" state. When the permit is granted, it moves to the \ref permitStates "GRANTED" state. When Release() is called, or the permit is revoked, the permit moves to the \ref permitStates "RELEASED" state (A permit can be forced directly to a \ref permitStates "RELEASED" state from \ref permitStates "REQUESTING".) A permit can never be re-requested, you must obtain a new permit. Permits are only revoked in exceptional circumstances, but you don't normally need to deal with this.

See Also:

   GameObject, Junction::RequestTrackPermit(), Track::RequestPermitForTrain(),
   Trackside::RequestTrackPermit(), Train