REF FASTPROCS                                        A. Sloman May 1990

        COPYRIGHT University of Sussex 1990. All Rights Reserved.

>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<                             >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<      FAST PROCEDURES        >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<                             >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

This REF file documents several fast procedures which do no checking  of
types or bounds.  See HELP * EFFICIENCY for  hints on optimising  Pop-11
programs.

         CONTENTS - (Use <ENTER> g to access required sections)

  1   Warning

  2   General Fast Structure Accessing Procedures

  3   Planting code for non-checking field access

  4   Fast Iteration

  5   Procedures to Reduce Garbage Collection on Lists

  6   Fast Operations on Properties

  7   Fast Prolog Operations

  8   Fast Integer Operators

  9   Fast Bit-wise Logical Operations on Simple Integers

 10   Fast Integer Vector Accessing

 11   Fast I/O Operations

 12   Fast Calling and Chaining Procedures

 13   Fast System Exit

 14   Repeated Warning



----------
1  Warning
----------

These "fast"  procedures are  used at  the risk  of the  user. They  are
potentially dangerous and can lead to spurious fault reports if misused.
They cannot be used on dynamic lists or on numbers other than  integers.
Fault reports involving the use of these procedures may be discounted if
the fault cannot be replicated using the non-fast alternatives which  do
type checking.



----------------------------------------------
2  General Fast Structure Accessing Procedures
----------------------------------------------

class_fast_subscr(vec_key) -> subscr_p                       [procedure]
        Returns non-checking subscriptor procedure for the class.


fast_cont(ref) -> item                                       [procedure]
item -> fast_cont(ref)
        For accessing or updating the contents of references.


fast_deref(ref) -> ref                                       [procedure]
        While ref is a reference with non-false cont, do

                cont(ref) -> ref

        If the contents are false return the reference.


fast_front(pair) -> item                                     [procedure]
item -> fast_front(pair)
        For accessing or updating the first element of a pair.


fast_back(pair) -> item                                      [procedure]
item -> fast_back(pair)
        For accessing or updating the second element of a pair.


fast_destpair(pair) -> back -> front                         [procedure]
        Equivalent to a call of fast_front then fast_back.


fast_flatten(list_1) -> list_2                               [procedure]
        Flatten a list using fast_front and fast_back.


fast_idval(ident) -> item                                    [procedure]
item -> fast_idval(ident)
        For accessing or updating  the value of  an identifier (same  as
        nonactive_idval in respect of active variables).


fast_lmember(item, list) -> sub_list                         [procedure]
        For finding an element in a list, testing with ==.


fast_member(item, list) -> bool                              [procedure]
        For finding an element in a list, testing with =.


fast_ncdelete(item, list_1)          -> list_2               [procedure]
fast_ncdelete(item, list_1, eq_p)    -> list_2
fast_ncdelete(item, list_1, n)       -> list_2
fast_ncdelete(item, list_1, eq_p, n) -> list_2
        Fast version of ncdelete,  which destructively deletes  matching
        occurrences of item from list_1. See REF * ncdelete.


fast_ncrev(list_1) -> list_2                                 [procedure]
        For reversing a list using existing list links.


fast_subscrs(n, string) -> char                              [procedure]
char -> fast_subscrs(n, string)
        For accessing or updating the n'th string element. Identical  to
        fsub_b (see below).


fast_subscrdstring(n, dstring) -> char                       [procedure]
char -> fast_subscrdstring(n, dstring)
        For accessing  or updating  the n'th  dstring element  (same  as
        fast_subscrs on ordinary strings).


fast_subscrvedstring(n, vstring) -> char                     [procedure]
char -> fast_subscrvedstring(n, vstring)
        For accessing  or updating  the n'th  vstring element.


fast_subscrintvec(n, intvec) -> int                          [procedure]
int -> fast_subscrintvec(n, intvec)
        For accessing or updating  the n'th integral  in an intvec  (see
        REF * INTVEC). Identical to fsub_si (see below)


fast_subscrshortvec(n, shortvec) -> int                      [procedure]
int -> fast_subscrshortvec(n, shortvec)
        For accessing or updating the  n'th integer in a shortvec  (see
        REF * INTVEC). Identical to fsub_ss (see below).


fast_subscrv(n, fvec) -> item                                [procedure]
item -> fast_subscrv(n, fvec)
        For accessing or updating the n'th element of a full vector.


fast_subscrw(n, word) -> char                                [procedure]
        For accessing  the n'th  character of  a word.  Updating is  not
        allowed.


fast_subscrl(n, list) -> item                                [procedure]
item -> fast_subscrl(n, list)
        A fast version of * subscrl  for accessing or updating the  n'th
        element of a  list (this  procedure does NOT  work with  dynamic
        lists).


fast_word_string(word) -> string                             [procedure]
        Returns the actual string of  characters of the word word  (i.e.
        without copying it, as word_string does). string must never have
        its characters updated, or the dictionary will be corrupted.


fast_frozval(n, clos) -> item                                [procedure]
item -> fast_frozval(n, clos)
        For accessing or updating the n'th frozen value of a closure.


The procedure cons_access, described in REF * KEYS makes it possible  to
create fast accessing procedures for a variety of data types.



----------------------------------------------
3  Planting code for non-checking field access
----------------------------------------------

See REF * sysFIELD.



-----------------
4  Fast Iteration
-----------------

fast_for                                                        [syntax]
endfast_for                                                     [syntax]
        For fast, non-type-checking  iteration over  lists or  integers.
        Formats are the same  as for, except that  the keyword step  may
        not be used, and non-integer numbers may not be used as  initial
        value, increment or final value. Dynamic lists may not be  used.
        May be terminated by endfor or endfast_for. See  REF * POPSYNTAX
        and HELP * FOR for formats.


fast_repeat                                                     [syntax]
endfast_repeat                                                  [syntax]
        A fast  non-type-checking version  of  repeat when  used  with a
        times clause on simple integer  values (without a times  clause,
        repeat and fast_repeat are the same).



---------------------------------------------------
5  Procedures to Reduce Garbage Collection on Lists
---------------------------------------------------

Two procedures are provided  that enable list links  to be re-used  when
they are no longer needed. Use of these procedures can be very dangerous
unless you know exactly what you are doing, and make sure that there are
no other pointers to the links (pairs).


sys_grbg_list(list)                                          [procedure]
        All the pairs  in the  list are chained  onto a  "free list"  of
        pairs, used by conspair.


sys_grbg_destpair(pair) -> back -> front                     [procedure]
        This, like destpair and fast_destpair takes a pair and puts  the
        front and the back of the pair on the stack. It also returns the
        pair itself  to  the  free  list,  unlike  sys_grbg_list,  which
        returns a whole chain of pairs to the free list.


The unfortunate abbreviation  'grbg' is  used rather  than 'garbage'  to
keep any corresponding file  names short enough  to be discriminated  in
Unix System V.



--------------------------------
6  Fast Operations on Properties
--------------------------------

fast_appproperty(prop, p)                                    [procedure]
        For procedures which do  not attempt to  update the property  in
        any way. Normal appproperty copies  the item/value pairs out  of
        the property into a vector first and then calls the procedure on
        each item and corresponding value. fast_appproperty applies  the
        procedure on the pairs directly in the property table.


fast_get_prop_entry(item, prop) -> prop_entry                [procedure]
        Enables a property entry data structure associating an item item
        and its value in a property to be accessed. If there is no  such
        entry, <false>  is  returned. Having  got  the entry,  the  next
        procedure can be used to access or update the value.


fast_prop_entry_value(prop_entry) -> value_item              [procedure]
value_item -> fast_prop_entry_value(prop_entry)
        This procedure can be used to access or update the value cell of
        a  property  entry  obtained  using  fast_get_prop_entry.   E.g.
        assuming that an  entry for  item exists in  the property  prop,
        then the  following instruction  can be  used to  increment  the
        value of prop(item) by amount x:

            prop(item) + x -> prop(item)

        However, this requires looking up the entry for item twice over,
        if it  already  exists.  Something  like  the  following  should
        therefore be much faster:

            lvars prop_entry = fast_get_prop_entry(item, prop);

            fast_prop_entry_value(prop_entry) + x
                -> fast_prop_entry_value(prop_entry)

        N.B: the above two procedures  do not check their arguments,  so
        they must be used with caution.


fast_prop_entry_arg(prop_entry) -> item                      [procedure]
        This procedure can be used to access the arg cell of a  property
        entry obtained using fast_get_prop_entry. It has no updater  for
        obvious reasons. See HELP * FOR_FORM/on_property for a  possible
        usage.


fast_kill_prop_entry(item, prop) -> bool                     [procedure]
        Removes, if present, the entry  associated with item from  prop;
        returning <true> if an entry was removed, and <false> otherwise.



-------------------------
7  Fast Prolog Operations
-------------------------

See REF * PROLOG. These procedures work only on prologterms (not pairs),
and do not dereference their arguments.


fast_prolog_arity(term) -> n                                 [procedure]
        Returns the arity of the prologterm term.


fast_prolog_functor(term) -> item                            [procedure]
item -> fast_prolog_functor(term)
        Returns or updates the functor item of the prologterm term.


fast_prolog_arg(n, term) -> item                             [procedure]
item -> fast_prolog_arg(n, term)
        Returns or updates the n-th argument of the prologterm term.



-------------------------
8  Fast Integer Operators
-------------------------

See REF * NUMBERS for the corresponding checking procedures.


i  fi_<   j -> bool                                         [operator 6]
i  fi_<=  j -> bool                                         [operator 6]
i  fi_>   j -> bool                                         [operator 6]
i  fi_>=  j -> bool                                         [operator 6]
        Fast less than, less than  or equal, greater than, greater  than
        or equal on two simple integers.


i  fi_+  j  -> k                                            [operator 5]
i  fi_-  j  -> k                                            [operator 5]
i  fi_*  j  -> k                                            [operator 4]
        Add/subtract/multiply two simple integers without checking.


i  fi_//   j  -> quot -> rem                                [operator 4]
i  fi_div  j  -> quot                                       [operator 2]
i  fi_rem  j  -> rem                                        [operator 2]
        Divide two simple  integers to give  remainder and quotient,  or
        either separately.


i  fi_mod  j                                                [operator 2]
        j modulo i.


fi_negate(i)                                                 [procedure]
        Negation of i.


fi_max(i, j) -> greatest                                     [procedure]
fi_min(i, j) -> least                                        [procedure]
        Greatest and least of two simple integers.


fi_check(item, low_int, hi_int) -> item                      [procedure]
        Checks item to be an integer within the range specified by lower
        bound low_int and upper bound hi_int (inclusive). Either or both
        bounds may be <false>  to indicate no upper  or lower limit.  If
        all conditions are satisfied  the procedure returns the  integer
        otherwise a mishap  occurs. This procedure  does not check  that
        low_int  and  hi_int   are  integers   if  non-false.   (Compare
        * checkinteger)



------------------------------------------------------
9  Fast Bit-wise Logical Operations on Simple Integers
------------------------------------------------------

i  fi_&&  j  -> k                                           [operator 4]
        Logical AND of two simple integers.


i  fi_&&~~  j -> k                                          [operator 4]
        AND  complement of two simple integers.


i  fi_||  j  -> k                                           [operator 4]
        Inclusive OR of two simple integers.


i  fi_||/&  j -> k                                          [operator 4]
        Exclusive OR of two simple integers.


fi_~~  i  -> j                                              [operator 4]
        Logical NOT of simple integer.


i  fi_<<  n                                                 [operator 4]
i  fi_>>  n                                                 [operator 4]
        Logical shift simple integer i left and right by n bits.



---------------------------------
10  Fast Integer Vector Accessing
---------------------------------

These procedures are provided to allow a consistent method of  accessing
vectors of integers of  various sizes. They  are all fast,  non-checking
functions, so they can be used on  any data types. Their primary use  is
for accessing  signed integer  vectors as  unsigned integers  (and  vice
versa), and  for  extreme cases  where  record-type structures  are  not
appropriate. For  example,  when  dealing with  disk  files  in  strange
formats, it is sometimes necessary to interpret the contents of the byte
addressable i/o buffer as holding an int (4 bytes) or short (2 bytes).


fsub_i(n, vec) -> int                                        [procedure]
int -> fsub_i(n, vec)
        Access/update the n'th  unsigned 32  bit integer  of the  vector
        vec.


fsub_si(n, vec) -> int                                       [procedure]
int -> fsub_si(n, vec)
        Access/update the n'th signed 32 bit integer of the vector vec.


fsub_s(n, vec) -> int                                        [procedure]
int -> fsub_s(n, vec)
        Access/update the n'th  unsigned 16  bit integer  of the  vector
        vec.


fsub_ss(n, vec) -> int                                       [procedure]
int -> fsub_ss(n, vec)
        Access/update the n'th signed 16 bit integer of the vector vec.


fsub_b(n, vec) -> int                                        [procedure]
int -> fsub_b(n, vec)
        Access/update the n'th unsigned 8 bit integer of the vector vec.


fsub_sb(n, vec) -> int                                       [procedure]
int -> fsub_sb(n, vec)
        Access (update) the n'th signed 8 bit integer of the vector vec.



-----------------------
11  Fast I/O Operations
-----------------------

fast_sysread(dev, bsub, bytestruct, nbytes) -> nread         [procedure]
fast_syswrite(dev, bsub, bytestruct, nbytes)                 [procedure]
        Same as sysread and syswrite  (see REF * SYSIO), except that  no
        checks are performed on any of the arguments. (Note that, unlike
        sysread and syswrite, the bsub  argument to these procedures  is
        not optional.)



----------------------------------------
12  Fast Calling and Chaining Procedures
----------------------------------------

fast_apply(p)                                                [procedure]
-> fast_apply(p)
        Executes the procedure p; the  update form executes the  updater
        of p. Neither form checks that p is a procedure (but the  update
        form does check that p has an updater).

        This procedure differs from the checking version, apply, in that
        it does not represent a stack frame, i.e. p is applied  directly
        inside the calling procedure.


fast_chain(p)                                                [procedure]
        Exits the current  procedure, restoring the  environment of  its
        caller, and then executes the procedure p without checking it to
        be a procedure.



--------------------
13  Fast System Exit
--------------------

fast_sysexit()                                               [procedure]
        Exits the Poplog system without doing any tidying actions.  That
        is, it does not  flush internal buffers,  does not call  popexit
        and does  not write  unwritten Ved  files. Its  main use  is  in
        forked child processes.



--------------------
14  Repeated Warning
--------------------

These fast procedures do no checking. For instance, there is no checking
of bounds of a string  or vector, or even that  object is a string  or a
vector. If  you  update  something which  you  shouldn't  the  resulting
behaviour will be totally undefined. Dynamic lists are not expanded.

    YOU USE THESE PROCEDURES AT YOUR  OWN RISK.

No help can be expected if any bugs occur whilst these procedures are in
use. The only aid available is LIB * SLOWPROCS which attempts to  change
all the fast  procedures into  their respective  checking versions.  For
LIB * SLOWPROCS to work  correctly it  must be loaded  before the  users
program is  compiled (recompile  after the  library has  been loaded  if
necessary). All  the fast  procedures in  (auto)loadable libraries  will
also need to be loaded before the  library is compiled if it is to  work
correctly.



--- C.all/ref/fastprocs
--- Copyright University of Sussex 1990. All rights reserved.
