The policy-cond Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The policy-cond Reference Manual

This is the policy-cond Reference Manual, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 12:24:34 2018 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

                             POLICY-COND
                             ===========

                           By Robert Smith

License
-------

This software is licensed under BSD 3-clause license. Please see LICENSE.


Environment Introspection
-------------------------

This library provides an interface to the CLtL2 environment
functions. Currently, only DECLARATION-INFORMATION is supported.


Temporarily Setting and Restoring Optimize Policy
-------------------------------------------------

One can use WITH-POLICY to temporarily set the global optimize policy
for e.g. loading systems. The original policy will be restored upon
completion.

WITH-POLICY should not be used with local declarations. In that case,
one should use LOCALLY.


Expansion Based on Policy
-------------------------
                           
POLICY-COND is a macro in order to select certain code paths based on
the current optimize compiler policy.

For example, given the following code:

(declaim (optimize (speed 0) (safety 3)))

(defun test-cond ()
  (policy-cond
    ((> speed safety) (+ 1 1))
    ((= speed safety) (+ 2 2))
    ((< speed safety) (+ 3 3))))

The function TEST-COND will get compiled as if it were

(defun test-cond ()
  (+ 3 3))

The optimize qualities SPEED, SAFETY, SPACE, DEBUG, and
COMPILATION-SPEED are guaranteed by an implementation. They can be
used as if they are lexically bound.

Currently, any expression for the policy expression can be used. In
the future, this might change to a limited set of operators.

Also included is POLICY-IF which behaves much like POLICY-COND, except
is akin to CL:IF.

Finally there is another package, POLICY, which exports IF, which is
intended to be used with reader macros. For example,

    #+#.(policy:if (<= speed safety)) (safe-algorithm)

Note that this does not work with local declarations. See

    http://clhs.lisp.se/Body/s_declar.htm#declare

for details.


Expectations
------------

An "expectation" is something the programmer expects to be true, but
could be wrong if the consumer of the code makes a logical
error. Expectations usually have different behavior in testing and
production environments. When testing, it is permitted that code be
slower due to sanity checking, and in production (after considerable
testing), it may make sense to remove extra sanity checking and add
speed improvements.

POLICY-COND offers the notion of an expectation, which can change with
policy. The macro POLICY-COND:WITH-EXPECTATIONS accomplishes this. It
is best described with an example.

    (defun vector-item (vec n)
      (with-expectations (> speed safety)
          ((type unsigned-byte         n)
           (type (vector single-float) vec)
           (assertion (< n (length vec))))
        (aref vec n)))

If the policy expression is not satisfied, then it will expand into

    (PROGN
      (CHECK-TYPE N UNSIGNED-BYTE)
      (CHECK-TYPE VEC (VECTOR SINGLE-FLOAT))
      (ASSERT (< N (LENGTH VEC)))
      (AREF VEC N))

But if it is satisfied, it will expand into

    (LOCALLY (DECLARE (TYPE UNSIGNED-BYTE N)
                      (TYPE (VECTOR SINGLE-FLOAT) VEC))
      (AREF VEC N))

In other words, we can read

    (with-expectations POLICY (EXPECTATIONS...) BODY...)

as

    "With the expectation that EXPECTATIONS are met when POLICY is
    true, execute BODY. Otherwise, ensure that they're true."

See the documentation string for WITH-EXPECTATIONS to see the kinds of
expectation clauses supported.


See Also
--------

For similar functionality for static function dispatch, see:

    https://bitbucket.org/tarballs_are_good/parameterized-function

Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 policy-cond

Maintainer

Robert Smith <quad@symbo1ics.com>

Author

Robert Smith <quad@symbo1ics.com>

License

BSD 3-clause (See LICENSE)

Description

Tools to insert code based on compiler policy.

Long Description

POLICY-COND provides tools to insert and execute code based on one’s compiler’s OPTIMIZE policy. It also contains a contract-like notion of ’expectations’, which allow dynamic checking or inclusion of various things to happen depending on compiler policy.

Dependency

sb-cltl2

Source

policy-cond.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Next: , Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 policy-cond.asd

Location

policy-cond.asd

Systems

policy-cond (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 policy-cond/package.lisp

Dependency

license.txt (file)

Parent

policy-cond (system)

Location

package.lisp

Packages

Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.3 policy-cond/policy-cond.lisp

Dependency

package.lisp (file)

Parent

policy-cond (system)

Location

policy-cond.lisp

Exported Definitions
Internal Definitions

policy (macro)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.4 policy-cond/expectations.lisp

Dependency

policy-cond.lisp (file)

Parent

policy-cond (system)

Location

expectations.lisp

Exported Definitions

with-expectations (macro)


Previous: , Up: Lisp files   [Contents][Index]

3.1.5 policy-cond/policy.lisp

Dependency

expectations.lisp (file)

Parent

policy-cond (system)

Location

policy.lisp

Exported Definitions

if (macro)


Previous: , Up: Files   [Contents][Index]

3.2 Other


Previous: , Up: Other files   [Contents][Index]

3.2.1 policy-cond/LICENSE.txt

Parent

policy-cond (system)

Location

LICENSE.txt


Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Next: , Previous: , Up: Packages   [Contents][Index]

4.1 policy

Source

package.lisp (file)

Use List

common-lisp

Exported Definitions

if (macro)


Previous: , Up: Packages   [Contents][Index]

4.2 policy-cond

Source

package.lisp (file)

Use List

common-lisp

Exported Definitions
Internal Definitions

policy (macro)


Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Macros

Macro: if FORM

Intended to be used with read macros. FORM should be a policy expression as described in POLICY-COND:POLICY-COND. For example,

#+#.(policy:if (> speed safety)) EXPRESSION

Package

policy

Source

policy.lisp (file)

Macro: policy-cond &body CASES

Like COND, except each clause predicate is a policy expression. A policy expression is a boolean expression using optimize declaration qualities such as SPEED, SAFETY, DEBUG, COMPILATION-SPEED, etc. as if they’re lexically bound to their actual value.

The result of POLICY-COND will be the first clause whose policy expression is satisfied. This is computed at compile time based off the current compiler policy.

Package

policy-cond

Source

policy-cond.lisp (file)

Macro: policy-if EXPR THEN ELSE

If the policy expression EXPR is true, then expand into THEN, otherwise into ELSE. The policy expression is as described in POLICY-COND.

Package

policy-cond

Source

policy-cond.lisp (file)

Macro: with-expectations POLICY (&rest EXPECTATIONS) &body BODY

Execute BODY with expectations laid out by the clauses EXPECTATIONS when the policy expression POLICY holds true. When POLICY does not hold true, then EXPECTATIONS will be explicitly checked at runtime.

EXPECTATIONS should be lists of one of the following forms.

Type Expectation: (TYPE <type> <vars-or-exprs>...)

Assert that the variables and expressions <vars-or-exprs> should
have the type <type>. If the POLICY is met, then declarations
will be made for the variables only.

Return Type Expectation: (RETURNS [<type>*])

Assert that the result of a form obeys a certain type. Multiple
types indicate multiple values are returned. If the POLICY is
met, then the assertion will be elided at runtime.

Assertion Expectation: (ASSERTION <assertion>)

Assert that the assertion <assertion> should be true. If the
POLICY is met, then the assertion will be elided at runtime.

Conditional Expectation: (OR-ELSE <predicate> <resulting action>)

Check that the predicate <predicate> is true, or else perform
<resulting action>. If the POLICY is met, elide the check and
action. This clause is principally used for having special
conditions get raised.

Inline Expectation: (INLINE [<symbol>*])

Inline the functions designated by the symbols <symbol> if POLICY
is met.

Package

policy-cond

Source

expectations.lisp (file)

Macro: with-policy POLICY &body BODY

Execute the body BODY with the global optimize policy set to POLICY. Once BODY has finished executing, restore the compiler policy to its original state.

For local declarations, use LOCALLY.

Package

policy-cond

Source

policy-cond.lisp (file)


Previous: , Up: Exported definitions   [Contents][Index]

5.1.2 Functions

Function: declaration-information SYMBOL &optional ENV

Get the declaration information for the environment ENV.

Package

policy-cond

Source

policy-cond.lisp (file)


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Macros

Macro: policy EXPR ENV
Package

policy-cond

Source

policy-cond.lisp (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   F   L   O   P  
Index Entry  Section

F
File, Lisp, policy-cond.asd: The policy-cond<dot>asd file
File, Lisp, policy-cond/expectations.lisp: The policy-cond/expectations<dot>lisp file
File, Lisp, policy-cond/package.lisp: The policy-cond/package<dot>lisp file
File, Lisp, policy-cond/policy-cond.lisp: The policy-cond/policy-cond<dot>lisp file
File, Lisp, policy-cond/policy.lisp: The policy-cond/policy<dot>lisp file
File, other, policy-cond/LICENSE.txt: The policy-cond/license<dot>txt file

L
Lisp File, policy-cond.asd: The policy-cond<dot>asd file
Lisp File, policy-cond/expectations.lisp: The policy-cond/expectations<dot>lisp file
Lisp File, policy-cond/package.lisp: The policy-cond/package<dot>lisp file
Lisp File, policy-cond/policy-cond.lisp: The policy-cond/policy-cond<dot>lisp file
Lisp File, policy-cond/policy.lisp: The policy-cond/policy<dot>lisp file

O
Other File, policy-cond/LICENSE.txt: The policy-cond/license<dot>txt file

P
policy-cond.asd: The policy-cond<dot>asd file
policy-cond/expectations.lisp: The policy-cond/expectations<dot>lisp file
policy-cond/LICENSE.txt: The policy-cond/license<dot>txt file
policy-cond/package.lisp: The policy-cond/package<dot>lisp file
policy-cond/policy-cond.lisp: The policy-cond/policy-cond<dot>lisp file
policy-cond/policy.lisp: The policy-cond/policy<dot>lisp file

Jump to:   F   L   O   P  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   D   F   I   M   P   W  
Index Entry  Section

D
declaration-information: Exported functions

F
Function, declaration-information: Exported functions

I
if: Exported macros

M
Macro, if: Exported macros
Macro, policy: Internal macros
Macro, policy-cond: Exported macros
Macro, policy-if: Exported macros
Macro, with-expectations: Exported macros
Macro, with-policy: Exported macros

P
policy: Internal macros
policy-cond: Exported macros
policy-if: Exported macros

W
with-expectations: Exported macros
with-policy: Exported macros

Jump to:   D   F   I   M   P   W  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables


Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   P   S  
Index Entry  Section

P
Package, policy: The policy package
Package, policy-cond: The policy-cond package
policy: The policy package
policy-cond: The policy-cond system
policy-cond: The policy-cond package

S
System, policy-cond: The policy-cond system

Jump to:   P   S