LISP: GC
C: L_GC
min args: 0
max args: 1
[F][SSCL]
SYNOPSIS:
gc &optional object
DESCRIPTION:
The gc function combines several functions related to the automatic storage reclamation (garbage collection) facility. This function takes one or zero arguments.
If no arguments are supplied, a garbage collection is immediately triggered on return to the top level, even if gc nil is in effect.
gc
t enables automatic garbage collection. In this case the runtime system will wait until a specified number of conses have been allocated (gc-level) and then reclaim (i.e. free) as much virtual memory as possible, both in cons space and on the heap.gc
nil disables automatic garbage collection; no garbage collection will take place (except for certain ephemeral collections). If you disable gc you will never be interrupted in the middle of an operation; however, running out of cons or heap space will be fatal to your program.gc
with a fixnum value sets the internal gc-level to that value; the gc-level is the number of conses to allocate before triggering another gc. The return value in this case is the value of gc-level. If 0 is supplied (an undefined value for gc-level), then the current value of gc-level is returned without changing gc-level.gc
with any other arbitrary object frees that object, without waiting for a garbage collection or checking whether the object is referred to. This is useful if you want to manually collect a very large object (such as an array) which you are absolutely sure you won't be needing ever again. The object is recursively de-allocated; all members of a list structure and arrays will get deallocated as well. The object may preserve its contents for some unspecified time after the freeing occurs, but this cannot be relied upon; once gc-ed the contents of an object must be assumed to be undefined.The function returns t if the operation suceeded and nil otherwise.
Some objects are not able to be freed because they do not consume any storage on the heap or in cons space (i.e. 'immediate' objects); nil will be returned in this case as well; the specific types are characters, lexical variable objects (but not the object they refer to), and compiled-function objects.
THEORY OF GARBAGE COLLECTION
This note explains the garbage collector; it is included here purely to satisfy your curiosity and assumes an intermediate-level understanding of LISP concepts. This explanation is purposely vague, since we can't tell you everything involved here for obvious reasons.
The Star Sapphire garbage collector, now in its second complete rewrite, uses a mark and sweep alogorithm. This means that while the collector is passive, there is very little gc related activity. When a certain number of conses have been allocated, a gc will be triggered; at this time the garbage collector is said to be 'active'.
There are four parts of the LISP process context that pertain to gc. The first is cons space; this is a region at the base of the workspace that contains the pool of conses; each cons is a 64 bit word. The second is the virtual heap, a region above cons space which contains objects of arbitrary size (with 64 bit granularity). The third is the stack, a segment of physical memory which contains intermediate results and a record of local scopes.
The last part is an 'invisible' hole between cons space and the heap which contains one bit for each 64 bit word in the workspace. This is used in the 'sweep' phase to mark active objects. This region of virtual memory (the 'map') is only accessed when the gc process is active.
The active gc process is divided into two phases; 'mark' and 'sweep'.
When a gc is triggered, the entire package system is traversed to 'mark' all active objects. Only objects which can be recursively referred to by symbols contained in valid packages are marked. Once that has occurred, all objects recursively referred to by objects contained on the stack are also marked, to allow gc while a program is running. Additionally, objects in certain internal hash tables relating to macros, the class system, etc. are marked.
In the sweep phase, the entire workspace is traversed; objects not marked in the map are freed. In cons space they are linked into a freelist; in the virtual heap they are freed using the heap facilities, which allow for automatic reclamation of arbitrarily sized blocks of virtual memory. Objects which are pure stack objects (like fixnums) do not need to be collected since they are 'forgotten' automatically in the normal course of evaluation.
NOTES:
The following notes apply to the behavior of gc when given a specific object. Understand that the garbage collector, when run on the full system, bypasses the limitations noted here (although it will be more time consuming). To make this distinction clear, the phrase 'submitting <object> to the gc function' is used repeatedly (as opposed to gc-ing a given <object> as part of a full gc).
Submitting certain system objects to the gc function (for instance, the result of (symbol-name 'car) or the symbol *print-level*) will most certainly trash the system environment without recourse. There is no check for whether any given gc <object> call will have disasterous effects, so use it carefully.
Submitting a package object to the gc function will fail. Use delete-package to remove a package.
Submitting a circular list to gc will result in the gc call not terminating; to remove a circular list you have to do a full gc.
Submitting a symbol to gc deletes the printname, as well as its value, functional value and property list; if it shares these objects with any other symbol, that symbol will be trashed even though its storage has not been reclaimed.
Submitting non-fixnum integers to gc does not free the integer; it instead sets the gc-level to that integer (non-fixnum integers 'contained' in other objects will be freed).
LISP: GCD
C: Lgcd
min args: 0
max args: -1
[F][CLTL 12]
SYNOPSIS:
gcd &rest integers
DESCRIPTION:
This returns the greatest common divisor of all the arguments, which must be integers. The result of gcd is always a non-negative integer. If one argument is given, its absolute value is returned. If no arguments are given, gcd returns 0, which is an identity for this operation. For three or more arguments,
(gcd a b c ... z) == (gcd (gcd a b) c ... z)
EXAMPLES:
(gcd 91 -49) => 7
(gcd 63 -42 35) => 7
(gcd 5) => 5
(gcd -4) => 4
(gcd) => 0
LISP: GENSYM
C: Lgensym
min args: 0
max args: 1
[F][CLTL 10]
SYNOPSIS:
gensym &optional x
DESCRIPTION:
The gensym function creates and returns a new symbol with an invented and somewhat anonymous print name.
The gensym function is usually used to create a symbol that should no normally be seen by the user and/or whose print name is unimportant except to allow easy distinction by eye between two such symbols. The optional argument is rarely supplied.
The name means "generate symbol," and the symbols produced by it are called "gensyms."
The symbol will be uninterned.
The invented print name is made up of a prefix (which defaults to G), followed by a decimal number which is the value of an internal global counter.
The counter is incremented by one every time gensym is called. In Star Sapphire Common LISP, this counter is implemented as a native unsigned long 32-bit integer. The counter starts out as 0 (although by the time initialization is done, gensym will have been used several times -- so don't depend on your code getting a counter value of zero the first time out).
The counter will wrap back to 0 when the highest value is reached. However, as the counter is a 32 bit number, it is improbable that wrapping will be a problem.
You can reset the counter to a desired value by giving an integer argument. This integer value must be non-negative. Otherwise the internal counter is incremented.
If the argument is a string, then that string is made the default gensym prefix.
After handling the argument if one is present, gensym creates a symbol as it would had no argument been given.
EXAMPLES:
(gensym) => G9
(gensym "*INTERNAL*-") => *INTERNAL*-10
(gensym 42) => *INTERNAL*-42
(gensym) => *INTERNAL*-43
(gensym "M-") => M-44
NOTES:
The ANSI Common LISP definition, in contrast, does not alter the counter state when the optional argument is supplied, instead using the value of a global variable *gensym-counter*; the use of a numeric argument in ANSI Common LISP is not recommended. Although Star Sapphire LISP does not support this yet, code which must remain stable in the future should be written with this in mind.
If it is desirable for the generated symbols to be interned, and yet guaranteed to be symbols distinct from all others, then the function gentemp may be more appropriate to use.
LISP: GENTEMP
C: Lgentemp
min args: 0
max args: 0
[F][CLTL 10]
SYNOPSIS:
gentemp &optional prefix package
DESCRIPTION:
The gentemp function creates and returns a new symbol much like gensym. A call to gentemp differs from gensym in that it interns the symbol in the package, and the symbol is guaranteed to be unique.
All gentemp symbols are prefixed with t if the prefix argument is omitted. Otherwise prefix (which must be a string) is used instead. If a package is specified, then the symbol is interned in that package, otherwise the symbol is interned in the user package.
The gentemp function guarantees the symbol will be a new one not already existing in the specified package. It does this by using an internal counter (which is separate from gensym's). If the generated symbol is not really new, then the process is repeated until a new one is created. There is no way to reset the gentemp counter.
LISP: GET
C: Lget
min args: 2
max args: 3
[F][CLTL 10]
SYNOPSIS:
get symbol indicator &optional default
DESCRIPTION:
The get function searches the property list of symbol for an indicator which is eq (i.e., very strictly equivalent) to the indicator.
The first argument must be a symbol. If a matching indicator is found, then the corresponding value is returned. If not, default is returned. If default is not specified, then nil is returned as the default.
Note that there is no way to distinguish an absent property from one whose value is default; if the absence of a property is important in your calculations, it is desireable to concoct a conventional value for property list defaults which is "obvious" such as not-in-this-property-list.
Here is how to use property lists.
Suppose that the property list of russian-leaders is (ivan :terrible catherine "great" gorbachev glastnost).
Then for example:
(get 'russian-leaders 'ivan) => :terrible
(get 'russian-leaders 'catherine) => "great"
(get 'russian-leaders 'gorbachev) => glastnost
setf
may be used with get to create a new property-value pair, possibly replacing an old pair with the same property name . For example:(get 'important-paintings 'leonardo) => nil
(setf (get 'important-paintings 'leonardo) 'mona-lisa) => mona-lisa
and now
(get 'important-paintings 'leonardo) => mona-lisa
This is the recommended way to add information to the property list of a symbol, both for sylistic reasons as well as for safety.
The default argument may be specified to get in a setf expression. The default will be ignored by setf.
However, default may be useful in such macros as push that are related to setf:
(push item (get sym 'my-stack '(base-item)))
means the approximately the same as
(setf (get sym 'my-stack '(base-item))
(cons item (get sym 'my-stack '(base-item))))
which in turn would be treated as simply
(setf (get sym 'my-stack)
(cons item (get sym 'my-stack '(base-item))))
LISP: GET-DECODED-TIME
C: GDT
min args: 0
max args: 0
[F][CLTL]
SYNOPSIS:
get-decoded-time
DESCRIPTION:
This function returns the current time in decoded time format. Nine values are returned: second, minute, hour, date, year, day-of-week, daylight-savings-time-p and time-zone.
NOTES:
See time functions for a description of decoded time format, and an explanation of how to set the default time-zone.
LISP: GET-DISPATCH-MACRO-CHARACTER
C: GetDMC
min args: 2
max args: 3
[F][CLTL 22]
SYNOPSIS:
get-dispatch-macro-character disp-char sub-char &optional readtable
DESCRIPTION:
get-dispatch-macro-character
returns the macro-character function for sub-char under disp-char or nil if there is no function associated with sub-char.If the sub-char is one of the ten decimal digits (0 1 2 3 4 5 6 7 8 9), get-dispatch-macro-character always returns nil. If sub-char is a lowercase character, its uppercase equivalent is used instead.
If nil is explicitly passed as the second argument to get-dispatch-macro-character, then the standard readtable is used. This is consistent with the behavior of copy-readtable.
An error is signaled if the specified disp-char is not in fact a dispatch character in the specified readtable. It is necessary to use make-dispatch-macro-character to set up the dispatch character before specifying its sub-characters.
SEE ALSO:
set-dispatch-macro-character, make-dispatch-macro-character.
LISP: GET-INTERNAL-REAL-TIME
C: GIREALT
min args: 0
max args: 1
[F][CLTL]
SYNOPSIS:
get-internal-real-time &optional (direct-hardware-access-p nil)
DESCRIPTION:
This returns the current internal real time, a hardware dependent quantity.
The specification states that there are no arguments to this function and only one return value. This function has been enhanced in this implementation; see below.
SEE ALSO:
time
functions.NOTES:
This function is principally used by the macro time in the file time.lsp to calculate time intervals to a fraction of a second.
In this implementation internal real time is the number of IBM PC clock ticks since midnight. These clock ticks occur roughly 18.2 times per second; see internal-time-units-per-second.
In this implementation two values are returned; the first is as specified, the internal real time value. The second value is a flag which is set whenever midnight occurs; this flag is cleared when it is read.
This implementation uses one of two methods to access the clock tick; either through BIOS interrupt 1Ah function 0; or directly by inspecting and poking locations in low memory. The default is to use the BIOS. If a second, non-nil argument is provided, the hardware is accessed directly, emulating the BIOS interrupt (including the behavior of the midnight flag).
Note that this second argument should only be used if your hardware does not support BIOS interrupt 1Ah function 0; only PC-XTs will not. In this case you must add an argument of t to all instances of this function in the file 'time.lsp' in the time macro.
There is no particular speed advantage to be gained by using int 1Ah emulation; this option is included only so that the time macro can work on PC-XTs; there should be no need to do so otherwise.
LISP: GET-INTERNAL-RUN-TIME
C: GIRUNT
min args: 0
max args: 0
[F][CLTL]
SYNOPSIS:
get-internal-run-time
DESCRIPTION:
This function returns the number of seconds since January 1, 1970 in local time as a single integer.
SEE ALSO:
time
functions.
LISP: GET-MACRO-CHARACTER
C: GetMC
min args: 1
max args: 2
[F][CLTL 22]
SYNOPSIS:
get-macro-character char &optional readtable
DESCRIPTION:
Get-macro-character
returns the function associated with char and, as a second value, returns the non-terminating-p flag; it returns nil if char does not have macro-character syntax. If nil is explicitly passed as the second argument to get-macro-character, then the standard readtable is used. This is consistent with the behavior of copy-readtable.SEE ALSO:
set-macro-character,
which has a complete description of the function parameter.
LISP: GET-SETF-METHOD
C: GET_SETF_METHOD
min args: 1
max args: 1
[F][CLTL 7]
SYNOPSIS:
get-setf-method form
DESCRIPTION:
The get-setf-method function returns five values which make up the setf method for form. The form must be a generalized variable reference. get-setf-method takes care of error-checking and macro expansion and guarantees to return exactly one store variable.
NOTES:
ANSI Common LISP has added an optional environment parameter which is not currently supported in Star Sapphire.
LISP: GET-SETF-METHOD-MULTIPLE-VALUE
C: GET_SETF_METHOD_MULTIPLE_VALUE
min args: 1
max args: 1
[F][CLTL 7]
SYNOPSIS:
get-setf-method-multiple-value form
DESCRIPTION:
The get-setf-method-multiple-value function returns five values which constitute the setf method for form, which must be a generalized variable reference. This is identical to get-setf-method except that it does not check the number of store variables to allow for multiple store variables. There are no such setf methods defined in Common LISP, but this function is intended to allow the programmer to do so.
NOTES:
ANSI Common LISP has added an optional environment parameter which is not currently supported in Star Sapphire.
LISP: GET-UNIVERSAL-TIME
C: GDT
min args: 0
max args: 0
[F][CLTL]
SYNOPSIS:
get-universal-time
DESCRIPTION:
This function returns the universal time as a single integer.
NOTES:
See time functions for a description of universal time.
LISP: GETF
C: Lgetf
min args: 2
max args: 3
[F][CLTL 10]
SYNOPSIS:
getf plist indicator &optional default
DESCRIPTION:
The getf function searches the property list plist for an indicator which is eq (i.e., very strictly equivalent) to the indicator.
The first argument must be a valid property list. If a matching indicator is found, then the corresponding value is returned. If not, default is returned. If a default is not specified, then nil serves as the default.
Note that there is no way to distinguish an absent property from one whose value is default; if the absence of a property is important in your calculations, it is desireable to concoct a conventional value for property list defaults which is "obvious" such as not-in-this-property-list.
Usually plist is computed from a generalized variable acceptable to setf.
Specifically:
(get x y) == (getf (symbol-plist x) y)
getf
may be used in a setf, in which case the plist must be acceptable as a expression which setf can use as a place.The effect is to add a new property/value pair, or update an existing pair, in the property list kept in the place.
The default argument may be specified to getf in this context; it is ignored by setf but may be useful in such macros as push that are related to setf. See the description of get for an example of this.
LISP: GETHASH
C: Lgethash
min args: 2
max args: 3
[F][CLTL 16]
SYNOPSIS:
gethash key hash-table &optional default
DESCRIPTION:
The gethash function obtains the entry in hash-table with key and returns two values.
The first return value is the value associated with the key if there is one. If there is no such entry, then gethash returns the default, which is either the third, optional argument or nil if none is specified.
The second return value is t if an entry was found and nil if no entry was found.
The default argument is useful when only the first return is being checked and nil is a possible value for an entry.
Setf
may be used with gethash to make new entries in a hash table. If an entry with the specified key already exists, its value is replaced with the new value.The setf method for gethash, which can be found in init0.lsp is as follows:
(defsetf gethash (k h &optional d) (v) `(puthash ,k ,h ,v))
This form must be run in order to use gethash in conjunction with setf. If you do not, you will get a message that setf does not know about gethash's setf method.
The default argument is ignored by setf in this context; other setf method utilizing macros such as incf may need this value, however.
LISP: GO
C: SFCGo, EGo
[S][CLTL 7]
SYNOPSIS:
go tag
DESCRIPTION:
The (go tag) special form is used to do a "go to" within a tagbody construct. The tag must a a symbol or an integer; the tag is not evaluated. go transfers control to the point in the body labelled by a tag eql to the one given. If there is no such tag in the body, the bodies of lexically containing tagbody constructs (if any) are examined as well. It is an error if there is no matching tag lexically visible to the point of the go.
The go form does not ever return a value.
As a matter of style, it is recommended that the user think twice before using a go. Most purposes of go can be accomplished with one of the iteration primitives, nested conditional forms, or return-from. If the use of go seems to be unavoidable, perhaps the control structure implemented by go should be packaged as a macro definition.
NOTES:
In Star Sapphire integer tags must be fixnums (i.e. an integer between -32,768 and 32,767).
LISP: GETLTYPE
C: L_getltype
min args: 1
max args: 1
[F][SSCL][DOS]
SYNOPSIS:
getltype object
DESCRIPTION:
The Star Sapphire specific getltype function acts exactly like type-of with a minor exception: The type specification symbol returned will be fixnum and bignum instead of integer for items of that type.
LISP: GRAPHIC-CHAR-P
C: LGrpCharP
min args: 1
max args: 1
[F][CLTL 13]
SYNOPSIS:
graphic-char-p char
DESCRIPTION:
The argument char must be a character object. graphic-char-p is true if the argument is a "graphic" (printing) character, and false it if is a "non-graphic" (formatting or control) character. Graphic characters have a standard textual representation as a single glyph, such as A or * or =. By convention, the space character is considered to be graphic. Of the standard characters all but #\Backspace, #\Tab, #\Rubout, #\Linefeed, #\Return, and #\Page are not graphic.