23: Using Permits

1. Permits restrict a process's activities in the telesphere.
   1. They may be imposed on a process by a programmer (when creating a process) or by an administrator (when a process enters a region or place).
   2. Every process has several different permits that work together to define the process's total restrictions.
2. The mix-in PermitProcess (used to define all processes) contains features used for working with permits
   1. Its attributes keep track of resource use and store the process's permits.
   2. Two important resources are age and charges.
      1. Age is the number of seconds a process has lived since construction.
      2. Charges are the number of teleclicks charged to a process since construction.
         1. Teleclicks are an abstract unit of measurement used to measure service rendered. They have no set definition. A service may charge a number of teleclicks to a process when the process uses that service's resources. Teleclicks may be used when billing a customer later.
   3. The mix-in has an operation that charges the process with teleclicks (by adding to the readonly charges attribute).
   4. These features work together to monitor and limit resource use.
3. A permit is an object of class Permit with attributes that define a process's capabilities.
   1. Action-granting attributes (set w/ a Boolean to be true or false)
      1. canGo, if true, allows an agent to call go on itself (described in an agent chapter) to travel to another place.
      2. canSend, if true, allows an agent to call send on itself (described in an agent chapter) to send clones to other places.
      3. canCreate, if true, allows a process to create peer processes.
      4. canRestart, if true, allows the engine to restart the process when terminated.
      5. canCharge, if true, allows a process to charge teleclicks (explained a little later) to another process.
      6. canGrant, if true, allows a process to grant a capability to the permit of another process (as described later).
      7. canDeny, if true, allows a process to deny a capability to the permit of another process (as described later).
   2. Resource-granting attributes (set as a positive integer value limiting the amount of a resource, or as nil for an unlimited grant of the resource).
      1. age, which sets the number of seconds a process may live past construction.
      2. charges, which sets the number of teleclicks that may be charged to a process after its construction. This is called the process's allowance.
      3. extent, which sets the maximum number of octets (bytes) in size that a process may become.
   3. Recognition attributes (set as an integer in a defined range)
      1. priority [-20, 20], which sets the process's execution priority in the multitasking world of the Telescript engine (discussed in a later chapter). Normal priority is 0.
      2. authenticity [0, 40], which sets ???
4. A process receives a set of permits when it is constructed--its permanent permits. Each permanent permit is stored in a different attribute of PermitProcess. The process may also acquire one or more temporary permits.
   1. Its native permit is passed in an as argument for construction. It accompanies the process no matter where it's located, and affects the process at all times.
   2. Its regional permit is assigned to the process when the process enters a region (which it does on construction and when--if it's an agent--it travels to a new region). The regional permit is assigned on construction by inheriting the regional permit of the process's creator. The regional permit affects the process as long as the process is in the region. (Regions are discussed in more detail in a places chapter.)
   3. Its local permit is assigned to the process when the process enters a place (on construction or after traveling). The local permit affects the process as long as the process is in the place.
   4. If a process executes a restrict block (described later in the chapter) in a method, that block applies a temporary permit to the process during execution of the block. Nested restrict blocks may apply more than one temporary permit at a time to a process.
5. A process has a single effective permit that directly limits its actions.
   1. The effective permit is an intersection of process's native, regional, and local permits and, (if it has any), its temporary permits.
      1. When two permits intersect, the resulting permit uses the most restrictive capabilities of the two original permits. For example, it has the smallest allowance permitted, the shortest age, and it can't perform any actions that aren't granted in both permits.
   2. The effective permit is stored in the readonly PermitProcess attribute "permit".
6. When a process is created, its permits depend on the permits of its parent process.
   1. When one process creates another process, it sets the native permit of the created process by supplying a permit as an argument for initialization.
      1. The native permit of the created process must be equal to or more constrictive than the effective process of the creating process.
         1. If the creating process has an infinite allowance (its charges attribute is nil), it can set the allowance of the created process to any amount.
         2. If the creating process has a finite allowance, the allowance of the created process is charged to the creator's allowance. Therefore the created allowance must be equal to or less than the creator's allowance.
      2. Because every process is created by another process (except engine places), all native permits are set with the limitations of their parent process.
   2. When one process creates another process, the engine sets the regional and local permits of the created process to be the same as the regional and local permits of its creator.
   3. When an agent travels by calling send on itself, it creates clones of itself. Each clone receives a duplicate of the parent agent's native permit with one exception: the charges attribute receives a number of teleclicks passed as an argument to "send". The number of teleclicks assigned is subtracted from the parent agent's charges attribute--so clone agents can't, in total, have more teleclicks than the parent agent had.
7. Once a process is created, other processes may be able to change its permits.
   1. If two processes are peers (have the same authority), one process can get or set the native permit of another if its own permit allows it those actions (through the attributes canGrant and canDeny).
      1. The only permissible resource increase is for the first process to increase the allowance of the second process, in which case the first process's allowance is decreased by the same amount. (This is the mechanism used to transfer teleclicks between processes.) Age and extent cannot be increased.
   2. If a process (or a sponsored op) has the same authority as the region, it can change the regional permits of other processes if its own permit allows it those actions.
   3. A place (or an op sponsored by that place) may change the local permits of its occupants if the place's own permit allows it those actions.
8. When an agent travels, its regional and local permits may change.
   1. When an agent enters a new region, the region may reset the agent's regional permit.
   2. When an agent enters a new place, the place may use its entering operation (described in the place chapter) to set the agent's local permit.
9. Violating or exhausting a permit
   1. As a process executes, it may exhaust or violate its effective permit, at which point the engine takes an appropriate action.
      1. If a process violates its permit, the engine throws the exception PermitViolated. A process violates its permit by trying to do any of the following:
         1. Taking an action forbidden by its effective permit
         2. Using a resource (age, charges, size) in an amount more than the intersection of temporary permits allows, but less than what the effective permit without those temporary permits would allow. (In other words, getting in trouble with a temporary permit, but not with the "permanent" permits.)
      2. If a process exhausts its permit, the engine terminates the process. A process exhausts its permit by trying to do the following:
         1. Using up a resource by matching or exceeding the amount specified by the process's permanent permits.
10. How a process uses up resources
    1. Age: Every op called expends a single teleclick.
    2. Charges: Teleclicks are charged to a process by calling charge on the process (a PermitProcess operation)
       1. The teleclicks are added to the process's charges attribute.
       2. The operation throws PermitViolated if the charge exceeds the process's permit. If so, the process isn't charged.
    3. Extent: Size is the approximate number of octets freed when the object is destroyed. (Size does not include its properties, which aren't destroyed.) If the object is a process, size is determined by all objects owned by the process.
11. Using a restrict block in a method
    1. The "restrict" keyword sets forth a restrict block.
    2. A permit follows "restrict" with a permit (or an expression that evaluates to a permit).
    3. The block that follows executes under the restrictions of the permit. If the process executing the block has a more restrictive permit than the block's permit, the process's restrictions take priority. In other words, a restrict block can't grant more capabilities than a process already has. It can only restrict them further.
    4. If executing the block violates the block permit, the block throws an exception
    5. A restrict block may have an optional catch clause that will catch any exception thrown by the restrict block and then execute a second block. (It works the same as the catch clause in a try block.)

Generated by the sweat of Mike Boom's brow.