[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
RE: [Gcl-devel] Various questions about GCL
|
From: |
Mike Thomas |
|
Subject: |
RE: [Gcl-devel] Various questions about GCL |
|
Date: |
Tue, 28 Sep 2004 06:31:12 +1000 |
|
User-agent: |
Mozilla/5.0 (Windows; U; Windows NT 5.0; en-US; rv:1.4) Gecko/20030624 Netscape/7.1 (ax) |
Hi Michael.
I'm only intermittently reading email at the moment hence the slow
replies. My answers below are based on supposition, so beware.
Would anyone be interested to do it? (I guess it's mainly a matter of
cut-n-paste from the "main" function).
Good question! I can't leap into it immediately and I suspect Camm is
in the same boat. Any help would be appreciated!
In addition to the cut and paste (or some #ifdefery) from main.c there
is a function called compiler::link which would probably need to be
modified so that the system linker (eg ld) can be asked to produce a
shared library/DLL rather than an executable.
Provided I haven't overlooked anything, this should be fairly easy to
do. What do you think Camm?
Is there any documentation about this? (I saw in gcl_japi.lsp that it
uses "defentry", but I couldn't find any doc about it;
In the GCL info directory there is a texinfo file called gcl-si.info-4
which describes these functions. Not sure how you would access it under
Unix, but if you have built GCL under Windows there should be an HTML
file called:
info/gcl-si/GCL-Specific.html
after GCL is built. I've pasted the texinfo file below - just search
for defentry.
I couldn't find the opengl or MPI extensions in the code, and
"make" in xgcl-2 fails...).
http://tapir-server.uwaterloo.ca/~mannr/software/OpenGL/
http://www.ccs.neu.edu/home/gene/pargcl.html
As with the X binding, I can't say whether these bindings still work
(they are Unix oriented Makefiles I believe), but you should get some
insights from the code.
The JAPI binding definitely works on Windows and should work on other
platforms too so can be regarded as current.
Can it be used to define C-functions located in a shared library
(to be loaded at run-time)?
On Unix I think that just by linking your GCL executable against a
shared lib (including your binding to the library) you get this,
likewise under Windows by linking against the import library for a DLL
(or with MinGW32 gcc - directly against the DLL in many cases). You
could also make the library statically linked.
If what you want is to avoid an executable which has been specially
linked against your shared library then I believe that, no, you can't at
runtime specify a shared library with defentry to be dynamically loaded.
On Windows, however, you could write a Lisp wrapper for LoadLibrary and
associated functions and then use the function pointers obtained to call
out to the DLL, thus avoiding a specially linked executable. I think
there is an approximate Unix equivalent (dlopen?)
Cheers
Mike Thomas.
=======================================================================
This is gcl-si.info, produced by makeinfo version 4.3 from gcl-si.texi.
This is a Texinfo GCL SYSTEM INTERNALS Manual
Copyright 1994 William F. Schelter
INFO-DIR-SECTION GNU Common Lisp
START-INFO-DIR-ENTRY
* gcl-si: (gcl-si.info). GNU Common Lisp System Internals
END-INFO-DIR-ENTRY
File: gcl-si.info, Node: Command Line, Next: Operating System
Definitions, Prev: Operating System, Up: Operating System
Command Line
============
The variable si::*command-args* is set to the list of strings passed
in when gcl is invoked.
Various flags are understood.
`-eval'
Call read and then eval on the command argument following `-eval'
`-load'
Load the file whose pathname is specified after `-load'.
`-f'
Replace si::*command-args* by the the list starting after `-f'.
Open the file following `-f' for input, skip the first line, and
then read and eval the rest of the forms in the file. This can
be used as with the shells to write small shell programs:
#!/usr/local/bin/gcl.exe -f
(format t "hello world ~a~%" (nth 1 si::*command-args*))
The value si::*command-args* will have the appropriate value.
Thus if the above 2 line file is made executable and called `foo'
then
tutorial% foo billy
hello world billy
NOTE: On many systems (eg SunOs) the first line of an executable
script file such as:
#!/usr/local/bin/gcl.exe -f
only reads the first 32 characters! So if your pathname where
the executable together with the '-f' amount to more than 32
characters the file will not be recognized. Also the executable
must be the actual large binary file, [or a link to it], and not
just a `/bin/sh' script. In latter case the `/bin/sh'
interpreter would get invoked on the file.
Alternately one could invoke the file `foo' without making it
executable:
tutorial% gcl -f foo "from bill"
hello world from bill
Finally perhaps the best way (why do we save the best for last..
I guess because we only figure it out after all the others..) The
following file `myhello' has 4 lines:
#!/bin/sh
#| Lisp will skip the next 2 lines on reading
exec gcl -f "$0" $ |#
(format t "hello world ~a~%" (nth 1 si::*command-args*))
marie% chmod a+x myhello
marie% myhello bill
hello world bill
The advantage of this method is that `gcl' can itself be a shell
script, which sets up environment and so on. Also the normal
path will be searched to find `gcl' The disadvantage is that this
would cause 2 invocations of `sh' and one invocation of `gcl'.
The plan using `gcl.exe' bypasses the `sh' entirely. Inded
invoking `gcl.exe' to print `hello world' is faster on most
systems than a similar `csh' or `bash' script, but slightly slower
than the old `sh'.
`-batch'
Do not enter the command print loop. Useful if the other command
line arguments do something. Do not print the License and
acknowledgement information. Note if your program does print any
License information, it must print the GCL header information also.
`-dir'
Directory where the executable binary that is running is located.
Needed by save and friends. This gets set as
si::*system-directory*
`-libdir'
-libdir `/d/wfs/gcl-2.0/'
would mean that the files like gcl-tk/tk.o would be found by
concatting the path to the libdir path, ie in
`/d/wfs/gcl-2.0/gcl-tk/tk.o'
`-compile'
Invoke the compiler on the filename following `-compile'. Other
flags affect compilation.
`-o-file'
If nil follows `-o-file' then do not produce an `.o' file.
`-c-file'
If `-c-file' is specified, leave the intermediate `.c' file there.
`-h-file'
If `-h-file' is specified, leave the intermediate `.h' file there.
`-data-file'
If `-data-file' is specified, leave the intermediate `.data' file
there.
`-system-p'
If `-system-p' is specified then invoke `compile-file' with the
`:system-p t' keyword argument, meaning that the C init function
will bear a name based on the name of the file, so that it may be
invoked by name by C code.
File: gcl-si.info, Node: Operating System Definitions, Prev: Command
Line, Up: Operating System
Operating System Definitions
============================
- Function: GET-DECODED-TIME ()
Package:LISP
Returns the current time in decoded time format. Returns nine
values: second, minute, hour, date, month, year, day-of-week,
daylight-saving-time-p, and time-zone.
- Function: HOST-NAMESTRING (pathname)
Package:LISP
Returns the host part of PATHNAME as a string.
- Function: RENAME-FILE (file new-name)
Package:LISP
Renames the file FILE to NEW-NAME. FILE may be a string, a
pathname, or a stream.
- Function: FILE-AUTHOR (file)
Package:LISP
Returns the author name of the specified file, as a string. FILE
may be a string or a stream
- Function: PATHNAME-HOST (pathname)
Package:LISP
Returns the host slot of PATHNAME.
- Function: FILE-POSITION (file-stream &optional position)
Package:LISP
Sets the file pointer of the specified file to POSITION, if
POSITION is given. Otherwise, returns the current file position
of the specified file.
- Function: DECODE-UNIVERSAL-TIME (universal-time &optional (timezone
-9))
Package:LISP
Converts UNIVERSAL-TIME into a decoded time at the TIMEZONE.
Returns nine values: second, minute, hour, date, month (1 - 12),
year, day-of-week (0 - 6), daylight-saving-time-p, and time-zone.
TIMEZONE in GCL defaults to 6, the time zone of Austin, Texas.
- Function: USER-HOMEDIR-PATHNAME (&optional host)
Package:LISP
Returns the home directory of the logged in user as a pathname.
HOST is ignored.
- Variable: *MODULES*
Package:LISP A list of names of the modules that have been loaded
into GCL.
- Function: SHORT-SITE-NAME ()
Package:LISP
Returns a string that identifies the physical location of the
current GCL.
- Function: DIRECTORY (name)
Package:LISP
Returns a list of files that match NAME. NAME may be a string, a
pathname, or a file stream.
- Function: SOFTWARE-VERSION ()
Package:LISP
Returns a string that identifies the software version of the
software under which GCL is currently running.
- Constant: INTERNAL-TIME-UNITS-PER-SECOND
Package:LISP The number of internal time units that fit into a
second.
- Function: ENOUGH-NAMESTRING (pathname &optional (defaults
*default-pathname-defaults*))
Package:LISP
Returns a string which uniquely identifies PATHNAME with respect to
DEFAULTS.
- Function: REQUIRE (module-name &optional (pathname))
Package:LISP
If the specified module is not present, then loads the appropriate
file(s). PATHNAME may be a single pathname or it may be a list of
pathnames.
- Function: ENCODE-UNIVERSAL-TIME (second minute hour date month year
&optional (timezone ))
Package:LISP
Does the inverse operation of DECODE-UNIVERSAL-TIME.
- Function: LISP-IMPLEMENTATION-VERSION ()
Package:LISP
Returns a string that tells you when the current GCL
implementation is brought up.
- Function: MACHINE-INSTANCE ()
Package:LISP
Returns a string that identifies the machine instance of the
machine on which GCL is currently running.
- Function: ROOM (&optional (x t))
Package:LISP
Displays information about storage allocation in the following
format.
for each type class
the number of pages so-far allocated for the type class
the maximum number of pages for the type class
the percentage of used cells to cells so-far allocated
the number of times the garbage collector has been
called to collect cells of the type class
the implementation types that belongs to the type class
the number of pages actually allocated for contiguous blocks
the maximum number of pages for contiguous blocks
the number of times the garbage collector has been called to
collect contiguous blocks
the number of pages in the hole
the maximum number of pages for relocatable blocks
the number of times the garbage collector has been called to
collect relocatable blocks
the total number of pages allocated for cells
the total number of pages allocated
the number of available pages
the number of pages GCL can use.
The number of times the garbage collector has been called is
not shown, if the number is zero. The optional X is ignored.
- Function: GET-UNIVERSAL-TIME ()
Package:LISP
Returns the current time as a single integer in universal time
format.
- Function: GET-INTERNAL-RUN-TIME ()
Package:LISP
Returns the run time in the internal time format. This is useful
for finding CPU usage. If the operating system allows, a second
value containing CPU usage of child processes is returned.
- Variable: *DEFAULT-PATHNAME-DEFAULTS*
Package:LISP The default pathname-defaults pathname.
- Function: LONG-SITE-NAME ()
Package:LISP
Returns a string that identifies the physical location of the
current GCL.
- Function: DELETE-FILE (file)
Package:LISP Deletes FILE.
- Function: GET-INTERNAL-REAL-TIME ()
Package:LISP
Returns the real time in the internal time format. This is useful
for finding elapsed time.
- Function: MACHINE-TYPE ()
Package:LISP
Returns a string that identifies the machine type of the machine
on which GCL is currently running.
- Macro: TIME
Package:LISP
Syntax:
(time form)
Evaluates FORM and outputs timing statistics on *TRACE-OUTPUT*.
- Function: SOFTWARE-TYPE ()
Package:LISP
Returns a string that identifies the software type of the software
under which GCL is currently running.
- Function: LISP-IMPLEMENTATION-TYPE ()
Package:LISP
Returns a string that tells you that you are using a version of
GCL.
- Function: SLEEP (n)
Package:LISP
This function causes execution to be suspended for N seconds. N
may be any non-negative, non-complex number.
File: gcl-si.info, Node: Structures, Next: Iteration and Tests, Prev:
Operating System, Up: Top
Structures
**********
- Macro: DEFSTRUCT
Package:LISP
Syntax:
(defstruct
{name | (name {:conc-name | (:conc-name prefix-string) |
:constructor | (:constructor symbol
[lambda-list]) |
:copier | (:copier symbol) |
:predicate | (:predicate symbol) |
(:include symbol) |
(:print-function function) |
(:type {vector | (vector type) | list}) |
:named | (:static { nil | t})
(:initial-offset number)}*)}
[doc]
{slot-name |
(slot-name [default-value-form] {:type type |
:read-only flag}*) }*
)
Defines a structure. The doc-string DOC, if supplied, is saved as
a STRUCTURE doc and can be retrieved by (documentation 'NAME
'structure). STATIC is gcl specific and makes the body non
relocatable.
See the files misc/rusage.lsp misc/cstruct.lsp, for examples of
making a lisp structure correspond to a C structure.
- Function: HELP (&optional symbol)
Package:LISP
GCL specific: Prints the documentation associated with SYMBOL.
With no argument, this function prints the greeting message to GCL
beginners.
File: gcl-si.info, Node: Iteration and Tests, Next: User Interface,
Prev: Structures, Up: Top
Iteration and Tests
*******************
- Macro: DO-EXTERNAL-SYMBOLS
Package:LISP
Syntax:
(do-external-symbols (var [package [result-form]])
{decl}* {tag | statement}*)
Executes STATEMENTs once for each external symbol in the PACKAGE
(which defaults to the current package), with VAR bound to the
current symbol. Then evaluates RESULT-FORM (which defaults to
NIL) and returns the value(s).
- Special Form: DO*
Package:LISP
Syntax:
(do* ({(var [init [step]])}*) (endtest {result}*)
{decl}* {tag | statement}*)
Just like DO, but performs variable bindings and assignments in
serial, just like LET* and SETQ do.
- Macro: DO-ALL-SYMBOLS
Package:LISP
Syntax:
(do-all-symbols (var [result-form]) {decl}* {tag | statement}*)
Executes STATEMENTs once for each symbol in each package, with VAR
bound to the current symbol. Then evaluates RESULT-FORM (which
defaults to NIL) and returns the value(s).
- Function: YES-OR-NO-P (&optional (format-string nil) &rest args)
Package:LISP
Asks the user a question whose answer is either 'YES' or 'NO'. If
FORMAT- STRING is non-NIL, then FRESH-LINE operation is performed,
a message is printed as if FORMAT-STRING and ARGs were given to
FORMAT, and then a prompt "(Yes or No)" is printed. Otherwise, no
prompt will appear.
- Function: MAPHASH #'hash-table
Package:LISP
For each entry in HASH-TABLE, calls FUNCTION on the key and value
of the entry; returns NIL.
- Function: MAPCAR (fun list &rest more-lists)
Package:LISP
Applies FUN to successive cars of LISTs and returns the results as
a list.
- Special Form: DOLIST
Package:LISP
Syntax:
(dolist (var listform [result]) {decl}* {tag | statement}*)
Executes STATEMENTs, with VAR bound to each member of the list
value of LISTFORM. Then returns the value(s) of RESULT (which
defaults to NIL).
- Function: EQ (x y)
Package:LISP
Returns T if X and Y are the same identical object; NIL otherwise.
- Function: EQUALP (x y)
Package:LISP
Returns T if X and Y are EQUAL, if they are characters and satisfy
CHAR-EQUAL, if they are numbers and have the same numerical value,
or if they have components that are all EQUALP. Returns NIL
otherwise.
- Function: EQUAL (x y)
Package:LISP
Returns T if X and Y are EQL or if they are of the same type and
corresponding components are EQUAL. Returns NIL otherwise.
Strings and bit-vectors are EQUAL if they are the same length and
have identical components. Other arrays must be EQ to be EQUAL.
- Macro: DO-SYMBOLS
Package:LISP
Syntax:
(do-symbols (var [package [result-form]]) {decl}* {tag |
statement}*)
Executes STATEMENTs once for each symbol in the PACKAGE (which
defaults to the current package), with VAR bound to the current
symbol. Then evaluates RESULT-FORM (which defaults to NIL) and
returns the value(s).
- Special Form: LOOP
Package:LISP
Syntax:
(loop {form}*)
Executes FORMs repeatedly until exited by a THROW or RETURN. The
FORMs are surrounded by an implicit NIL block.
File: gcl-si.info, Node: User Interface, Next: Doc, Prev: Iteration
and Tests, Up: Top
User Interface
**************
- Special Variable: -
Package:LISP Holds the top-level form that GCL is currently
evaluating.
- Function: - (number &rest more-numbers)
Package:LISP
Subtracts the second and all subsequent NUMBERs from the first
NUMBER. With one arg, negates it.
- Macro: UNTRACE
Package:LISP
Syntax:
(untrace {function-name}*)
Removes tracing from the specified functions. With no
FUNCTION-NAMEs, untraces all functions.
- Variable: ***
Package:LISP Gets the previous value of ** when GCL evaluates a
top-level form.
- Function: MAKE-STRING-INPUT-STREAM (string &optional (start 0) (end
(length string)))
Package:LISP
Returns an input stream which will supply the characters of String
between Start and End in order.
- Macro: STEP
Package:LISP
Syntax:
(step form)
Evaluates FORM in the single-step mode and returns the value.
- Variable: *BREAK-ENABLE*
Package:LISP GCL specific: When an error occurrs, control enters
to the break loop only if the value of this variable is non-NIL.
- Special Variable: /
Package:LISP Holds a list of the values of the last top-level form.
- Function: DESCRIBE (x)
Package:LISP
Prints a description of the object X.
- Function: ED (&optional x)
Package:LISP
Invokes the editor. The action depends on the version of GCL.
- Variable: *DEBUG-IO*
Package:LISP Holds the I/O stream used by the GCL debugger.
- Variable: *BREAK-ON-WARNINGS*
Package:LISP When the function WARN is called, control enters to
the break loop only if the value of this varialbe is non-NIL.
- Function: CERROR (continue-format-string error-format-string &rest
args)
Package:LISP
Signals a correctable error.
- Variable: **
Package:LISP Gets the previous value of * when GCL evaluates a
top-level form.
- Special Variable: +++
Package:LISP Gets the previous value of ++ when GCL evaluates a
top-level form.
- Function: INSPECT (x)
Package:LISP
Shows the information about the object X in an interactive manner
- Special Variable: //
Package:LISP Gets the previous value of / when GCL evaluates a
top-level form.
- Variable: *TRACE-OUTPUT*
Package:LISP The trace output stream.
- Special Variable: ++
Package:LISP Gets the previous value of + when GCL evaluates a
top-level form.
- Variable: *ERROR-OUTPUT*
Package:LISP Holds the output stream for error messages.
- Function: DRIBBLE (&optional pathname)
Package:LISP
If PATHNAME is given, begins to record the interaction to the
specified file. If PATHNAME is not given, ends the recording.
- Variable: *
Package:LISP Holds the value of the last top-level form.
- Special Variable: ///
Package:LISP Gets the previous value of // when GCL evaluates a
top-level form.
- Function: WARN (format-string &rest args)
Package:LISP
Formats FORMAT-STRING and ARGs to *ERROR-OUTPUT* as a warning
message.
- Function: BREAK (&optional (format-string nil) &rest args)
Package:LISP
Enters a break loop. If FORMAT-STRING is non-NIL, formats
FORMAT-STRING and ARGS to *ERROR-OUTPUT* before entering a break
loop. Typing :HELP at the break loop will list the break-loop
commands.
- Special Variable: +
Package:LISP Holds the last top-level form.
- Macro: TRACE
Package:LISP
Syntax:
(trace {function-name}*)
Traces the specified functions. With no FUNCTION-NAMEs, returns a
list of functions currently being traced.
Additional Keywords are allowed in GCL with the syntax (trace {fn
| (fn {:kw form}*)}*)
For each FN naming a function, traces that function. Each :KW
should be one of the ones listed below, and FORM should have the
corresponding form. No :KW may be given more than once for the
same FN. Returns a list of all FNs now traced which weren't
already traced.
EXAMPLE (Try this with your favorite factorial function FACT):
;; print entry args and exit values
(trace FACT)
;; Break coming out of FACT if the value is bigger than 1000.
(trace (fact :exit
(progn
(if (> (car values) 1000)(break "big result"))
(car values))))
;; Hairy example:
;;make arglist available without the si:: prefix
(import 'si::arglist)
(trace (fact
:DECLARATIONS
((in-string "Here comes input: ")
(out-string "Here comes output: ")
all-values
(silly (+ 3 4)))
:COND
(equal (rem (car arglist) 2) 0)
:ENTRY
(progn
(cond
((equal (car arglist) 8)
(princ "Entering FACT on input 8!! ")
(setq out-string "Here comes output from inside
(FACT 8): "))
(t
(princ in-string)))
(car arglist))
:EXIT
(progn
(setq all-values (cons (car values) all-values))
(princ out-string)
(when (equal (car arglist) 8)
;; reset out-string
(setq out-string "Here comes output: "))
(cons 'fact values))
:ENTRYCOND
(not (= (car arglist) 6))
:EXITCOND
(not (= (car values) (* 6 (car arglist))))
:DEPTH
5))
Syntax is `:keyword' form1 `:keyword' form2 ...
`:declarations'
DEFAULT: NIL
FORM is ((var1 form1 )(var2 form2 )...), where the var_i
are symbols distinct from each other and from all symbols
which are similarly declared for currently traced functions.
Each form is evaluated immediately. Upon any invocation of
a traced function when not already inside a traced function
call, each var is bound to that value of form .
`:COND'
DEFAULT: T
Here, FORM is any Lisp form to be evaluated (by EVAL) upon
entering a call of FN, in the environment where si::ARGLIST
is bound to the current list of arguments of FN. Note that
even if the evaluation of FORM changes the value of
SI::ARGLIST (e.g. by evaluation of (SETQ si::ARGLIST ...)),
the list of arguments passed to FN is unchanged. Users may
alter args passed by destructively modifying the list
structure of SI::ARGLIST however. The call is traced (thus
invoking the :ENTRYCOND and :EXITCOND forms, at least) if and
only if FORM does not evaluate to NIL.
`:ENTRYCOND'
DEFAULT: T
This is evaluated (by EVAL) if the :COND form evaluates to
non-NIL, both in an environment where SI::ARGLIST is bound to
the current list of arguments of FN. If non-NIL, the :ENTRY
form is then evaluated and printed with the trace "prompt".
`:ENTRY'
DEFAULT: (CONS (QUOTE x) SI::ARGLIST),
where x is the symbol we call FN If the :COND and :ENTRYCOND
forms evaluate to non-NIL, then the trace "prompt" is printed
and then this FORM is evaluated (by EVAL) in an environment
where SI::ARGLIST is bound to the current list of arguments
of FN. The result is then printed.
`:EXITCOND'
DEFAULT: T
This is evaluated (by EVAL) in the environment described
below for the :EXIT form. The :EXIT form is then evaluated
and printed with the "prompt" if and only if the result here
is non-NIL.
`:EXIT'
DEFAULT: (CONS (QUOTE x) VALUES),
where x is the symbol we call FN Upon exit from tracing a
given call, this FORM is evaluated (after the appropriate
trace "prompt" is printed), using EVAL in an environment
where SI::ARGLIST is bound to the current list of arguments
of FN and VALUES is bound to the list of values returned by
FN (recalling that Common Lisp functions may return multiple
values).
`:DEPTH'
DEFAULT: No depth limit
FORM is simply a positive integer specifying the maximum
nesting of traced calls of FN, i.e. of calls of FN in which
the :COND form evaluated to non-NIL. For calls of FN in
which this limit is exceeded, even the :COND form is not
evaluated, and the call is not traced.
File: gcl-si.info, Node: Doc, Next: Type, Prev: User Interface, Up: Top
Doc
***
- Function: APROPOS (string &optional (package nil))
Package:LISP
Prints those symbols whose print-names contain STRING as substring.
If PACKAGE is non-NIL, then only the specified package is searched.
- Function: INFO (string &optional (list-of-info-files
*default-info-files*))
PACKAGE:SI
Find all documentation about STRING in LIST-OF-INFO-FILES. The
search is done for STRING as a substring of a node name, or for
STRING in the indexed entries in the first index for each info
file. Typically that should be a variable and function definition
index, if the info file is about a programming language. If the
windowing system is connected, then a choice box is offered and
double clicking on an item brings up its documentation.
Otherwise a list of choices is offered and the user may select
some of these choices.
list-of-info-files is of the form
("gcl-si.info" "gcl-tk.info" "gcl.info")
The above list is the default value of *default-info-files*, a
variable in the SI package. To find these files in the file
system, the search path *info-paths* is consulted as is the master
info directory `dir'.
see *Index *default-info-files*:: and *Index *info-paths*::. For
example
(info "defun")
0: DEFUN :(gcl-si.info)Special Forms and Functions.
1: (gcl.info)defun.
Enter n, all, none, or multiple choices eg 1 3 : 1
Info from file /home/wfs/gcl-doc/gcl.info:
defun
[Macro]
---------------------------------------------------------------------------
`Defun' function-name lambda-list [[{declaration}* |
documentation]]
...
would list the node `(gcl.info)defun'. That is the node entitled
`defun' from the info file gcl.info. That documentation is based
on the ANSI common lisp standard. The choice
DEFUN :(gcl-si.info)Special Forms and Functions.
refers to the documentation on DEFUN from the info file
gcl-si.info in the node Special Forms And Functions. This is an
index reference and only the part of the node which refers to
`defun' will be printed.
(info "factor" '("maxima.info"))
would search the maxima info files index and nodes for `factor'.
- Variable: *info-paths*
Package SI:
A list of strings such as
'("" "/usr/info/" "/usr/local/lib/info/" "/usr/local/info/"
"/usr/local/gnu/info/" )
saying where to look for the info files. It is used implicitly
by `info', see *Index info::.
Looking for maxima.info would look for the file maxima.info in all
the directories listed in *info-paths*. If nto found then it
would look for `dir' in the *info-paths* directories, and if it
were found it would look in the `dir' for a menu item such as
* maxima: (/home/wfs/maxima-5.0/info/maxima.info).
If such an entry exists then the directory there would be used for
the purpose of finding `maxima.info'
File: gcl-si.info, Node: Type, Next: GCL Specific, Prev: Doc, Up: Top
Type
****
- Function: COERCE (x type)
Package:LISP
Coerces X to an object of the type TYPE.
- Function: TYPE-OF (x)
Package:LISP
Returns the type of X.
- Function: CONSTANTP (symbol)
Package:LISP
Returns T if the variable named by SYMBOL is a constant; NIL
otherwise.
- Function: TYPEP (x type)
Package:LISP
Returns T if X is of the type TYPE; NIL otherwise.
- Function: COMMONP (x)
Package:LISP
Returns T if X is a Common Lisp object; NIL otherwise.
- Function: SUBTYPEP (type1 type2)
Package:LISP
Returns T if TYPE1 is a subtype of TYPE2; NIL otherwise. If it
could not determine, then returns NIL as the second value.
Otherwise, the second value is T.
- Macro: CHECK-TYPE
Package:LISP
Syntax:
(check-type place typespec [string])
Signals an error, if the contents of PLACE are not of the
specified type.
- Macro: ASSERT
Package:LISP
Syntax:
(assert test-form [({place}*) [string {arg}*]])
Signals an error if the value of TEST-FORM is NIL. STRING is an
format string used as the error message. ARGs are arguments to
the format string.
- Macro: DEFTYPE
Package:LISP
Syntax:
(deftype name lambda-list {decl | doc}* {form}*)
Defines a new type-specifier abbreviation in terms of an
'expansion' function (lambda lambda-list1 {decl}* {form}*)
where lambda-list1 is identical to LAMBDA-LIST except that all
optional parameters with no default value specified in LAMBDA-LIST
defaults to the symbol '*', but not to NIL. When the type system
of GCL encounters a type specifier (NAME arg1 ... argn), it calls
the expansion function with the arguments arg1 ... argn, and uses
the returned value instead of the original type specifier. When
the symbol NAME is used as a type specifier, the expansion
function is called with no argument. The doc-string DOC, if
supplied, is saved as the TYPE doc of NAME, and is retrieved by
(documentation 'NAME 'type).
- Declaration: DYNAMIC-EXTENT
Package:LISP Declaration to allow locals to be cons'd on the C
stack. For example (defun foo (&rest l) (declare (:dynamic-extent
l)) ...) will cause l to be a list formed on the C stack of the
foo function frame. Of course passing L out as a value of foo
will cause havoc. (setq x (make-list n)) (setq x (cons a b))
(setq x (list a b c ..)) also are handled on the stack, for
dynamic-extent x.
File: gcl-si.info, Node: GCL Specific, Next: C Interface, Prev: Type,
Up: Top
GCL Specific
************
- Function: SYSTEM (string)
Package:LISP
GCL specific: Executes a Shell command as if STRING is an input to
the Shell. Not all versions of GCL support this function. At
least on POSIX systems, this call should return two integers
represeting the exit status and any possible terminating signal
respectively.
- Variable: *IGNORE-MAXIMUM-PAGES*
Package:SI GCL specific: Tells the GCL memory manager whether
(non-NIL) or not (NIL) it should expand memory whenever the
maximum allocatable pages have been used up.
- Variable: *OPTIMIZE-MAXIMUM-PAGES*
Package:SI
GCL specific: Tells the GCL memory manager whether to attempt to
adjust the maximum allowable pages for each type to approximately
optimize the garbage collection load in the current process.
Defaults to T. Set to NIL if you care more about memory usage
than runtime.
- Function: MACHINE-VERSION ()
Package:LISP
Returns a string that identifies the machine version of the machine
on which GCL is currently running.
- Function: BY ()
Package:LISP
GCL specific: Exits from GCL.
- Macro: DEFCFUN
Package:LISP
Syntax:
(defcfun header n {element}*)
GCL specific: Defines a C-language function which calls Lisp
functions and/or handles Lisp objects. HEADER gives the header of
the C function as a string. Non-negative-integer is the number of
the main stack entries used by the C function, primarily for
protecting Lisp objects from being garbage-collected. Each
ELEMENT may give a C code fragment as a string, or it may be a list
((symbol {arg}*) {place}*) which, when executed, calls the Lisp
function named by SYMBOL with the specified arguments and saves
the value(s) to the specified places. The DEFCFUN form has the
above meanings only after compiled; The GCL interpreter simply
ignores this form.
An example which defines a C function list2 of two arguments, but
which calls the 'lisp' function CONS by name, and refers to the
constant 'NIL. Note to be loaded by `load' the function should be
static.
(defCfun "static object list2(x,y) object x,y;" 0
"object z;" ('NIL z) ((CONS y z) z)
((CONS x z) z) "return(z);" )
In lisp the operations in the body would be (setq z 'nil)
(setq z (cons y z)) (setq z (cons x z))
Syntax:
(defCfun header non-negative-integer
{ string
| ( function-symbol { value }* )
| (( function-symbol { value }* ) { place
}* ) })
value:
place:
{ C-expr | ( C-type C-expr ) }
C-function-name:
C-expr:
{ string | symbol }
C-type:
{ object | int | char | float | double }
- Macro: CLINES
Package:LISP
Syntax:
(clines {string}*)
GCL specific: The GCL compiler embeds STRINGs into the
intermediate C language code. The interpreter ignores this form.
- Function: ALLOCATE (type number &optional (really-allocate nil))
Package:LISP
GCL specific: Sets the maximum number of pages for the type class
of the GCL implementation type TYPE to NUMBER. If REALLY-ALLOCATE
is given a non-NIL value, then the specified number of pages will
be allocated immediately.
- Function: GBC (x)
Package:LISP
GCL specific: Invokes the garbage collector (GC) with the
collection level specified by X. NIL as the argument causes GC to
collect cells only. T as the argument causes GC to collect
everything.
- Function: SAVE (pathname)
Package:LISP
GCL specific: Saves the current GCL core image into a program file
specified by PATHNAME. This function depends on the version of
GCL. The function si::save-system is to be preferred in almost
all circumstances. Unlike save, it makes the relocatable section
permanent, and causes no future gc of currently loaded .o files.
- Function: HELP* (string &optional (package 'lisp))
Package:LISP
GCL specific: Prints the documentation associated with those
symbols in the specified package whose print names contain STRING
as substring. STRING may be a symbol, in which case the
print-name of that symbol is used. If PACKAGE is NIL, then all
packages are searched.
- Macro: DEFLA
Package:LISP
Syntax:
(defla name lambda-list {decl | doc}* {form}*)
GCL specific: Used to DEFine Lisp Alternative. For the
interpreter, DEFLA is equivalent to DEFUN, but the compiler
ignores this form.
- Function: PROCLAMATION (decl-spec)
Package:LISP
GCL specific: Returns T if the specified declaration is globally
in effect; NIL otherwise. See the doc of DECLARE for possible
DECL-SPECs.
- Macro: DEFENTRY
Package:LISP
Syntax:
(defentry name arg-types c-function)
GCL specific: The compiler defines a Lisp function whose body
consists of a calling sequence to the C language function
specified by C-FUNCTION. The interpreter ignores this form. The
ARG-TYPES specifies the C types of the arguments which C-FUNCTION
requires. The list of allowed types is (object char int float
double string). Code will be produced to coerce from a lisp
object to the appropriate type before passing the argument to the
C-FUNCTION. The c-function should be of the form (c-result-type
c-fname) where c-result-type is a member of (void object char int
float double string). c-fname may be a symbol (in which case it
will be downcased) or a string. If c-function is not a list, then
(object c-function) is assumed. In order for C code to be loaded
in by `load' you should declare any variables and functions to be
static. If you will link them in at build time, of course you
are allowed to define new externals.
Sample usage:
--File begin-----
;; JOE takes X a lisp string and Y a fixnum and returns a
character.
(clines "#include \"foo.ch\"")
(defentry joe (string int) (char "our_c_fun"))
---File end------
---File foo.ch---
/* C function for extracting the i'th element of a string */
static char our_c_fun(p,i)
char *p;
int i;
{
return p[i];
}
-----File end---
One must be careful of storage allocation issues when passing a
string. If the C code invokes storage allocation (either by
calling `malloc' or `make_cons' etc), then there is a possibility
of a garbage collection, so that if the string passed was not
constructed with `:static t' when its array was constructed, then
it could move. If the C function may allocate storage, then you
should pass a copy:
(defun safe-c-string (x)
(let* ((n (length x))
(a (make-array (+ n 1) :element-type 'string-char
:static t :fill-pointer n)))
(si::copy-array-portion x y 0 0 n)
(setf (aref a n) (code-char 0)))
a)
- Function: COPY-ARRAY-PORTION (x,y,i1,i2,n1)
Package:SI Copy elements from X to Y starting at X[i1] to Y[i2]
and doing N1 elements if N1 is supplied otherwise, doing the
length of X - I1 elements. If the types of the arrays are not the
same, this has implementation dependent results.
- Function: BYE ( &optional (exit-status 0))
Package:LISP
GCL specific: Exits from GCL with exit-status.
- Function: USE-FAST-LINKS (turn-on)
Package:LISP
GCL specific: If TURN-ON is not nil, the fast link mechanism is
enabled, so that ordinary function calls will not appear in the
invocation stack, and calls will be much faster. This is the
default. If you anticipate needing to see a stack trace in the
debugger, then you should turn this off.
* Menu:
* Bignums::
File: gcl-si.info, Node: Bignums, Prev: GCL Specific, Up: GCL Specific
Bignums
=======
A directory mp was added to hold the new multi precision arithmetic
code. The layout and a fair amount of code in the mp directory is an
enhanced version of gpari version 34. The gpari c code was rewritten to
be more efficient, and gcc assembler macros were added to allow
inlining of operations not possible to do in C. On a 68K machine, this
allows the C version to be as efficient as the very carefully written
assembler in the gpari distribution. For the main machines, an
assembler file (produced by gcc) based on this new method, is included.
This is for sites which do not have gcc, or do not wish to compile
the whole system with gcc.
Bignum arithmetic is much faster now. Many changes were made to
cmpnew also, to add 'integer' as a new type. It differs from variables
of other types, in that storage is associated to each such variable,
and assignments mean copying the storage. This allows a function which
does a good deal of bignum arithmetic, to do very little consing in the
heap. An example is the computation of PI-INV in scratchpad, which
calculates the inverse of pi to a prescribed number of bits accuracy.
That function is now about 20 times faster, and no longer causes
garbage collection. In versions of GCL where HAVE_ALLOCA is defined,
the temporary storage growth is on the C stack, although this often not
so critical (for example it makes virtually no difference in the PI-INV
example, since in spite of the many operations, only one storage
allocation takes place.
Below is the actual code for PI-INV
On a sun3/280 (cli.com)
Here is the comparison of lucid and gcl before and after on that
pi-inv. Times are in seconds with multiples of the gcl/akcl time in
parentheses.
On a sun3/280 (cli.com)
pi-inv akcl-566 franz lucid old kcl/akcl
----------------------------------------
10000 3.3 9.2(2.8 X) 15.3 (4.6X) 92.7 (29.5 X)
20000 12.7 31.0(2.4 X) 62.2 (4.9X) 580.0 (45.5 X)
(defun pi-inv (bits &aux (m 0))
(declare (integer bits m))
(let* ((n (+ bits (integer-length bits) 11))
(tt (truncate (ash 1 n) 882))
(d (* 4 882 882))
(s 0))
(declare (integer s d tt n))
(do ((i 2 (+ i 2))
(j 1123 (+ j 21460)))
((zerop tt) (cons s (- (+ n 2))))
(declare (integer i j))
(setq s (+ s (* j tt))
m (- (* (- i 1) (- (* 2 i) 1) (- (* 2 i) 3)))
tt (truncate (* m tt) (* d (the integer (expt i
3))))))))
File: gcl-si.info, Node: C Interface, Next: System Definitions, Prev:
GCL Specific, Up: Top
C Interface
***********
* Menu:
* Available Symbols::
File: gcl-si.info, Node: Available Symbols, Prev: C Interface, Up: C
Interface
Available Symbols
=================
When GCL is built, those symbols in the system libraries which are
referenced by functions linked in in the list of objects given in
`unixport/makefile', become available for reference by GCL code.
On some systems it is possible with `faslink' to load `.o' files
which reference other libraries, but in general this practice is not
portable.