Clozure Common Lisp

The map-file-to-ivector function tries to open the file at pathname for reading. If successful, the function maps the file's contents to a range of virtual addresses. If successful, it returns a read-only vector whose element-type is given by element-type, and whose contents are the contents of the memory-mapped file.

pathname

The pathname of the file to be memory-mapped.

element-type

The element-type of the vector to be created. Specified as a type-specifier that names a subtype of either signed-byte or unsigned-byte.

The returned vector is a displaced-array whose element-type is (UPGRADED-ARRAY-ELEMENT-TYPE element-type). The target of the displaced array is a vector of type (SIMPLE-ARRAY element-type (*)) whose elements are the contents of the memory-mapped file.

Because of alignment issues, the mapped file's contents start a few bytes (4 bytes on 32-bit platforms, 8 bytes on 64-bit platforms) into the vector. The displaced array returned by map-file-to-ivector hides this overhead, but it's usually more efficient to operate on the underlying simple 1-dimensional array. Given a displaced array (like the value returned by map-file-to-ivector), the function array-displacement returns the underlying array and the displacement index in elements.

Currently, Clozure CL supports only read operations on memory-mapped files. If you try to change the contents of an array returned by map-file-to-ivector, Clozure CL signals a memory error.

If the argument is a displaced-array returned by map-file-to-ivector, and if it has not yet been unmapped by this function, then unmap-ivector undoes the memory mapping, closes the mapped file, and changes the displaced-array so that its target is an empty vector (of length zero).

This function is a synonym for (map-file-to-ivector pathname '(unsigned-byte 8)) It is provided as a convenience for the common case of memory-mapping a file as a vector of bytes.

This function is a synonym for unmap-ivector

Proclaims the variable special, assigns the variable the supplied value, and assigns the docstring to the variable's variable documentation. Marks the variable static, preventing any attempt to dynamically rebind it. Any attempt to dynamically rebind var signals an error.

Saves a heap image.

filename

The pathname of the file to be created when Clozure CL saves the application.

toplevel-function

The function to be executed after startup is complete. The toplevel is a function of no arguments that performs whatever actions the lisp system should perform when launched with this image.

If this parameter is not supplied, Clozure CL uses its default toplevel. The default toplevel runs the read-eval-print loop.

init-file

The pathname of a Lisp file to be loaded when the image starts up. You can place initialization expressions in this file, and use it to customize the behavior of the Lisp system when it starts up.

error-handler

The error-handling mode for the saved image. The supplied value determines what happens when an error is not handled by the saved image. Valid values are :quit (Lisp exits with an error message); :quit-quietly (Lisp exits without an error message); or :listener (Lisp enters a break loop, enabling you to debug the problem by interacting in a listener). If you don't supply this parameter, the saved image uses the default error handler (:listener).

application-class

The CLOS class that represents the saved Lisp application. Normally you don't need to supply this parameter; save-application uses the class ccl:lisp-development-system. In some cases you may choose to create a custom application class; in that case, pass the name of the class as the value for this parameter.

clear-clos-caches

If true, ensures that CLOS caches are emptied before saving the image. Normally you don't need to supply this parameter, but if for some reason you want to ensure the CLOS caches are clear when the image starts up, you can pass any true value.

purify

When true, calls (in effect) purify before saving the heap image. This moves certain objects that are unlikely to become garbage to a special memory area that is not scanned by the GC (since it is expected that the GC wouldn't find anything to collect).

impurify

If true, calls (in effect) impurify before saving the heap image. (If both :impurify and :purify are true, first impurify is done, and then purify.)

impurify moves objects in certain special memory areas into the regular dynamic heap, where they will be scanned by the GC.

mode

A number specifying the mode (permission bits) of the output file.

prepend-kernel

Specifies the file to prepend to the saved heap image. A value of t means to prepend the lisp kernel binary that the lisp started with. Otherwise, the value of :prepend-kernel should be a pathname designator for the file to be prepended.

If the prepended file is executable, its execute mode bits will be copied to the output file.

This argument can be used to prepend any kind of file to the saved heap image. This can be useful in some special cases.

native

If true, saves the image as a native (ELF, Mach-O, PE) shared library. (On platforms where this isn't yet supported, a warning is issued and the option is ignored.)

This variable contains a list of 0-argument functions that will be called before saving a heap image. Users may add functions to this list as needed.

This variable contains a list of 0-argument functions that will be called after restoring a saved heap image. Users may add functions to this list as needed.

This variable contains a list of 0-argument functions that will be called before quitting the lisp.

Note that save-application quits the lisp, so any functions on this list will be invoked before saving a heap image.

This variable contains a list of 0-argument functions that will be called after starting the lisp.

This function reads the fasl files specified by the list fasl-files and combines them into a single fasl file named output-file. The :if-exists keyword argument is interpreted as in the standard function open.

Loading the concatenated fasl file has the same effect as loading the individual input fasl files in the specified order.

The pathname-type of the output file and of each input file defaults to the current platform's fasl file type (see Platform-specific filename conventions). If any of the input files has a different type an error will be signaled, but fasl-concatenate doesn't otherwise try too hard to verify that the input files are real fasl files for the current platform.

Return the state of exception-enable and rounding-mode control flags for the current thread.

When called without the optional mode argument, this function returns a plist of keyword/value pairs which describe the floating point exception-enable and rounding-mode flags for the current thread.

If mode is supplied, it should be one of the keywords :rounding-mode, :overflow, :underflow, :division-by-zero, :invalid, or :inexact. The value of corresponding control flag is returned.

rounding-mode

One of :nearest, :zero, :positive, or :negative

overflow, underflow, division-by-zero, invalid, inexact

If t, the floating-point exception is signaled. If nil, it is masked.

Set the state of exception-enable and rounding-mode control flags for the current thread.

rounding-mode

If supplied, must be one of :nearest, :zero, :positive, or :negative.

overflow, underflow, division-by-zero, invalid, inexact

NIL to mask the exception, T to signal it.

Sets the current thread's exception-enable and rounding-mode control flags to the indicated values for arguments that are supplied, and preserves the values associated with those that aren't supplied.

Ensure cleanup-forms are executed.

In Clozure CL, the cleanup forms are always executed as if they were wrapped with without-interrupts. To allow interrupts, use with-interrupts-enabled.

When true, warn will enter a break loop.

This variable was removed from ANSI CL. The rationale was that the same effect may be achieved with (setq *break-on-signals* 'warning).

When true (the default), lisp will enter a break loop when an error is signaled.

When true, automatically print the available restarts before entering a break loop.

The trace macro encapsulates the functions named by specs, causing trace actions to take place on entry and exit from each function. The default actions print a message on function entry and exit. Keyword/value options can be used to specify changes in the default behavior.

Invoking (trace) without arguments returns a list of functions being traced.

A spec is either a symbol that is the name of a function, or an expression of the form (setf symbol), or a specific method of a generic function in the form (:method gf-name {qualifier}* ({specializer}*)), where a specializer can be the name of a class or an EQL specializer.

A spec can also be a string naming a package, or equivalently a list (:package package-name), in order to request that all functions in the package to be traced.

By default, whenever a traced function is entered or exited, a short message is printed on *trace-output* showing the arguments on entry and values on exit. Options specified as key/value pairs can be used to modify this behavior. Options preceding the function specs apply to all the functions being traced. Options specified along with a spec apply to that spec only and override any global options. The following options are supported:

:methods {T | nil}

If true, and if applied to a spec naming a generic function, arranges to trace all the methods of the generic function in addition to the generic function itself.

:inside outside-spec | ({outside-spec}*)

Inhibits all trace actions unless the current invocation of the function being traced is inside one of the outside-spec's, i.e. unless a function named by one of the outside-spec's is currently on the stack. outside-spec can name a function, a method, or a package, as above.

:if form, :condition form

Evaluates form whenever the function being traced is about to be entered, and inhibits all trace actions if form returns nil. The form may reference the lexical variable ccl::args, which is a list of the arguments in this call. :condition is just a synonym for :if, though if both are specified, both must return non-nil.

:before-if form

Evaluates form whenever the function being traced is about to be entered, and inhibits the entry trace actions if form returns nil. The form may reference the lexical variable ccl::args, which is a list of the arguments in this call. If both :if and :before-if are specified, both must return non-nil in order for the before entry actions to happen.

:after-if form

Evaluates form whenever the function being traced has just exited, and inhibits the exit trace actions if form returns nil. The form may reference the lexical variable ccl::vals, which is a list of values returned by this call. If both :if and :after-if are specified, both must return non-nil in order for the after exit actions to happen.

:print-before form

Evaluates form whenever the function being traced is about to be entered, and prints the result before printing the standard entry message. The form may reference the lexical variable ccl::args, which is a list of the arguments in this call. To see multiple forms, use values: :print-before (values (one-thing) (another-thing)).

:print-after form

Evaluates form whenever the function being traced has just exited, and prints the result after printing the standard exit message. The form may reference the lexical variable ccl::vals, which is a list of values returned by this call. To see multiple forms, use values: :print-after (values (one-thing) (another-thing)).

:print form

Equivalent to :print-before form :print-after form.

:eval-before form

Evaluates form whenever the function being traced is about to be entered. The form may reference the lexical variable ccl::args, which is a list of the arguments in this call.

:eval-after form

Evaluates form whenever the function being has just exited. The form may reference the lexical variable ccl::vals, which is a list of values returned by this call.

:eval form

Equivalent to :eval-before form :eval-after form.

:break-before form

Evaluates form whenever the function being traced is about to be entered, and if the result is non-nil, enters a debugger break loop. The form may reference the lexical variable ccl::args, which is a list of the arguments in this call.

:break-after form

Evaluates form whenever the function being traced has just exited, and if the result is non-nil, enters a debugger break loop. The form may reference the lexical variable ccl::vals, which is a list of values returned by this call.

:break form

Equivalent to :break-before form :break-after form.

:backtrace-before form, :backtrace form

Evaluates form whenever the function being traced is about to be entered. The form may reference the lexical variable ccl::args, which is a list of the arguments in this call. The value returned by form is interpreted as follows:

nil

does nothing

:detailed

prints a detailed backtrace to *trace-output*.

(:detailed integer)

prints the top integer frames of detailed backtrace to *trace-output*.

integer

prints top integer frames of a terse backtrace to *trace-output*.

anything else

prints a terse backtrace to *trace-output*.

Note that unlike with the other options, :backtrace is equivalent to :backtrace-before only, not both before and after, since it's usually not helpful to print the same backtrace both before and after the function call.

:backtrace-after form

Evaluates form whenever the function being traced has just exited. The form may reference the lexical variable ccl::vals, which is a list of values returned by this call. The value returned by form is interpreted as follows:

nil

does nothing

:detailed

prints a detailed backtrace to *trace-output*.

(:detailed integer)

prints the top integer frames of detailed backtrace to *trace-output*.

integer

prints top integer frames of a terse backtrace to *trace-output*.

anything else

prints a terse backtrace to *trace-output*.

:beforeaction

specifies the action to be taken just before the traced function is entered. action is one of:

:print

The default, prints a short indented message showing the function name and the invocation arguments

:break

Equivalent to :before :print :break-before t

:backtrace

Equivalent to :before :print :backtrace-before t

function

Any other value is interpreted as a function to call on entry instead of printing the standard entry message. It is called with its first argument being the name of the function being traced, the remaining arguments being all the arguments to the function being traced, and *trace-level* bound to the current nesting level of trace actions.

:afteraction

specifies the action to be taken just after the traced function exits. action is one of:

:print

The default, prints a short indented message showing the function name and the returned values

:break

Equivalent to :after :print :break-after t

:backtrace

Equivalent to :after :print :backtrace-after t

function

Any other value is interpreted as a function to call on exit instead of printing the standard exit message. It is called with its first argument being the name of the function being traced, the remaining arguments being all the values returned by the function being traced, and ccl:*trace-level* bound to the current nesting level of trace actions.

Variable bound to the current nesting level during execution of before and after trace actions. The default printing actions use it to determine the amount of indentation.

The default before and after print actions will not indent by more than the value of *trace-max-indent* regardless of the current trace level.

This is a functional version of the TRACE macro. spec and keywords are as for TRACE, except that all arguments are evaluated.

The default print actions bind *print-level* to this value while printing. Note that this rebinding is only in effect during the default entry and exit messages. It does not apply to printing of :print-before/:print-after forms or any explicit printing done by user code.

The default print actions bind *print-length* to this value while printing. Note that this rebinding is only in effect during the default entry and exit messages. It does not apply to printing of :print-before/:print-after forms or any explicit printing done by user code.

By default, this is nil. If non-nil it should be a integer, and the default entry and exit messages will print a | instead of space every this many levels of indentation.

Add a piece of advice to the function or method specified by spec according to form.

spec

A specification of the function on which to put the advice. This is either a symbol that is the name of a function or generic function, or an expression of the form (setf symbol), or a specific method of a generic function in the form (:method symbol {qualifiers} (specializer {specializer})).

form

A form to execute before, after, or around the advised function. The form can refer to the variable arglist that is bound to the arguments with which the advised function was called. You can exit from form with (return).

name

A name that identifies the piece of advice.

when

An argument that specifies when the piece of advice is run. There are three allowable values. The default is :before, which specifies that form is executed before the advised function is called. Other possible values are :after, which specifies that form is executed after the advised function is called, and :around, which specifies that form is executed around the call to the advised function. Use (:do-it) within form to indicate invocation of the original definition.

With the function foo defined as follows

(defun foo (numlist)
  (apply '+ numlist))
	

(advise foo (if (some #'(lambda (n) (not (numberp n))) (car arglist))
	      0
	      (:do-it))
	:when :around :name :zero-if-not-nums)
	

To do the same thing using a :before piece of advice:

(advise foo (if (some #'(lambda (n) (not (numberp n))) (car arglist))
	      (return 0))
	:when :before :name :zero-if-not-nums)
	

Remove the piece or pieces of advice matching spec, when, and name.

The unadvise macro removes the piece or pieces of advice matching spec, when, and name. When the value of spec is t and the values of when and name are nil, unadvise removes every piece of advice; when spec is t, the argument when is nil, and name is non-nil, unadvise removes all pieces of advice with the given name.

The arguments have the same meaning as in advise.

Return a list of the pieces of advice matching spec, when, and name.

The advisedp macro returns a list of existing pieces of advice that match spec, when, and name. When the value of spec is t and the values of when and name are nil, advisedp returns all existing pieces of advice.

The arguments have the same meaning as in advise.

Monitor a lisp object for writes.

object

Any memory-allocated lisp object.

The WATCH function arranges for the specified object to be monitored for writes. This is accomplished by copying the object to its own set of virtual memory pages, which are then write-protected. This protection is enforced by the computer's memory-management hardware; the write-protection does not slow down reads at all.

When any write to the object is attempted, a WRITE-TO-WATCHED-OBJECT condition will be signaled.

When called with no arguments, WATCH returns a freshly-consed list of the objects currently being watched.

WATCH returns NIL if the object cannot be watched (typically because the object is in a static or pure memory area).

WATCH operates at a fairly low level; it is not possible to avoid the details of the internal representation of objects. Nevertheless, as a convenience, WATCHing a standard-instance, a hash-table, or a multi-dimensional or non-simple CL array will watch the underlying slot-vector, hash-table-vector, or data-vector, respectively.

WATCH can monitor any memory-allocated lisp object.

In Clozure CL, a memory-allocated object is either a cons cell or a uvector.

WATCH operates on cons cells, not lists. In order to watch a chain of cons cells, each cons cell must be watched individually. Because each watched cons cell takes up its own own virtual memory page (4 Kbytes), it's only feasible to watch relatively short lists.

If a memory-allocated object isn't a cons cell, then it is a vector-like object called a uvector. A uvector is a memory-allocated lisp object whose first word is a header that describes the object's type and the number of elements that it contains.

So, a hash table is a uvector, as is a string, a standard instance, a double-float, a CL array or vector, and so forth.

Some CL objects, like strings and other simple vectors, map in a straightforward way onto the uvector representation. It is easy to understand what happens in such cases. The uvector index corresponds directly to the vector index:

? (defvar *s* "xxxxx")
*S*
? (watch *s*)
"xxxxx"
? (setf (char *s* 3) #\o)
> Error: Write to watched uvector "xxxxx" at index 3
>        Faulting instruction: (movl (% eax) (@ -5 (% r15) (% rcx)))
> While executing: SET-CHAR, in process listener(1).
> Type :POP to abort, :R for a list of available restarts.
> Type :? for other options.

In the case of more complicated objects (e.g., a hash-table, a standard-instance, a package, etc.), the elements of the uvector are like slots in a structure. It's necessary to know which one of those "slots" contains the data that will be changed when the object is written to.

As mentioned above, watch knows about arrays, hash-tables, and standard-instances, and will automatically watch the appropriate data-containing element.

An example might make this clearer.

? (defclass foo ()
    (slot-a slot-b slot-c))
#<STANDARD-CLASS FOO>
? (defvar *a-foo* (make-instance 'foo))
*A-FOO*
? (watch *a-foo*)
#<SLOT-VECTOR #xDB00D>
;;; Note that WATCH has watched the internal slot-vector object
? (setf (slot-value *a-foo* 'slot-a) 'foo)
> Error: Write to watched uvector #<SLOT-VECTOR #xDB00D> at index 1
>        Faulting instruction: (movq (% rsi) (@ -5 (% r8) (% rdi)))
> While executing: %MAYBE-STD-SETF-SLOT-VALUE-USING-CLASS, in process listener(1).
> Type :POP to abort, :R for a list of available restarts.
> Type :? for other options.

Looking at a backtrace would presumably show what object and slot name were written.

Note that even though the write was to slot-a, the uvector index was 1 (not 0). This is because the first element of a slot-vector is a pointer to the instance that owns the slots. We can retrieve that to look at the object that was modified:

1 > (uvref (write-to-watched-object-object *break-condition*) 0)
#<FOO #x30004113502D>
1 > (describe *)
#<FOO #x30004113502D>
Class: #<STANDARD-CLASS FOO>
Wrapper: #<CLASS-WRAPPER FOO #x300041135EBD>
Instance slots
SLOT-A: #<Unbound>
SLOT-B: #<Unbound>
SLOT-C: #<Unbound>
1 >

Stop monitoring a lisp object for writes.

The UNWATCH function ensures that the specified object is in normal, non-monitored memory. If the object is not currently being watched, UNWATCH does nothing and returns NIL. Otherwise, the newly unwatched object is returned.

Condition signaled when a write to a watched object is attempted.

This condition is signaled when a watched object is written to. There are three slots of interest:

object

The actual object that was the destination of the write.

offset

The byte offset from the tagged object pointer to the address of the write.

instruction

The disassembled machine instruction that attempted the write.

A few restarts are provided: one will skip over the faulting write instruction and proceed; another offers to unwatch the object and continue.

There is also an emulate restart. In some common cases, the faulting write instruction can be emulated, enabling the write to be performed without having to unwatch the object (and therefore let other threads potentially write to it). If the faulting instruction isn't recognized, the emulate restart will not be offered.

This function walks the lisp heap, collects information about the objects stored on the heap, and prints a report of the results to the stream specified by the keyword argument :stream. It shows the number of objects of each type, the sum of their logical sizes (the size of the data part of the object) and the sum of their physical sizes (the total size as computed by object-direct-size).

If :gc-first is true (the default), heap-utilization does a full gc before scanning the heap.

If :classes is true, objects are classified by class rather than just basic type.

The keyword argument :area can be used to restrict the walk to one memory area or a list of areas. Some possible values are :dynamic, :static, :managed-static, and :readonly. By default, all areas (including stacks) are examined.

The keyword argument :sort can be one of :count, :logical-size, or :physical-size to sort output by count or size.

By default, sizes are shown in bytes. The keyword argument :unit can be :kb, :mb, or :gb to show sizes in those units.

If :start is non-nil, it should be an object returned by ccl::get-allocation-sentinel; only objects at higher address are scanned (roughly, only objects allocated after it).

If threshold is non-nil, it should be a number between 0 and 1. All types whose share of the heap is less than threshold will be lumped together in an “All Others” line rather than being listed individually.

This function returns the size of thing in bytes, including any headers and alignment overhead. It does not descend into an object's components.

This function returns the address of thing as an integer. If thing is a fixnum, thing is simply returned.

Note that there are types other than fixnums that are represented as immediate values rather than heap-allocated objects. On various platforms, these might include characters and single-floats, and possibly other values. The %address-of function will return fairly useless values for such objects.

The value returned by %address-of is only useful for debugging, since the GC may run at any time and may move objects around in memory, thereby changing their addresses.

When true, the output of disassemble may include platform-dependent additional information. For instance, on the x86 ports, the output will include the x86 opcode bytes.

The default value is nil.

When true, record source file information for definitions.

This variable governs how source location information is recorded.

nil

Do not record source location information. Filename information for definitions will still be saved if *record-source-file* is true.

t

Store source location information, including the original source text, for function objects and definitions.

:no-text

Store source location information, but do not store a copy of the original source text. This is an optimization useful for compiling files that are not expected to change.

When true, record PC to source mapping (but only if *save-source-locations* is also true).

Return the source-note object for the function f.

Return the filename for source.

Return the starting file position (not character position) for the thing described by source-note.

Return the ending file position (not character position) for the thing described by source-note.

Return the saved source text delimited by start and end.

Read the source text from the original file if it is not already present in source-note.

The value of this variable is used when :external-format is unspecified or specified as :default. It can meaningfully be given any value that can be used as an external-format (except for the value :default.)

The initial value of this variable in Clozure CL is :unix, which is equivalent to (:line-termination :unix), among other things.

The value of this variable is used when an external-format doesn't specify a line-termination convention (or specifies it as :default.) It can meaningfully be given any value that can be used as a line termination keyword (see Line Termination Keywords).

The initial value of this variable in Clozure CL is :unix.

Either creates a new external format object, or return an existing one with the same specified slot values.

domain

This is used to indicate where the external format is to be used. Its value can be almost anything. It defaults to NIL. There are two domains that have a pre-defined meaning in Clozure CL: :file indicates encoding for a file in the file system and :socket indicates i/o to/from a socket. The value of domain affects the default values for character-encoding and line-termination.

character-encoding

A keyword that specifies the character encoding for the external format. Character Encodings. Defaults to :default which means if domain is :file use the value of the variable *default-file-character-encoding* and if domain is :socket, use the value of the variable *default-socket-character-encoding*. The initial value of both of these variables is NIL, which means the :iso-8859-1 encoding.

line-termination

A keyword that indicates a line termination keyword Line Termination Keywords. Defaults to :default which means use the value of the variable *default-line-termination*.

external-format

An external-format object as described above.

Despite the function's name, it doesn't necessarily create a new, unique external-format object: two calls to make-external-format with the same arguments made in the same dynamic environment return the same (eq) object.

Writes descriptions of all defined character encodings to *terminal-io*. These descriptions include the names of the encoding’s aliases and a doc string which briefly describes each encoding’s properties and intended use.

Make a socket.

address-family

The address/protocol family of this socket. Currently, :internet (the default), meaning IPv4, :internet6, meaning IPv6, and :file, referring to UNIX domain addresses, are supported.

type

One of :stream (the default) to request a connection-oriented socket, or :datagram to request a connectionless socket. The default is :stream.

connect

This argument is only relevant to sockets of type :stream. One of :active (the default) to request a :passive to request a file or TCP listener socket.

eol

This argument is currently ignored (it is accepted for compatibility with Franz Allegro).

format

One of :text (the default), :binary, or :bivalent. This argument is ignored for :stream sockets for now, as :stream sockets are currently always bivalent (i.e. they support both character and byte I/O). For :datagram sockets, this argument is ignored (the format of a datagram socket is always :binary).

remote

For TCP streams, it specifies the socket address to connect to, specified as socket-address instance. Ignored for listener sockets. For UDP sockets, it can be used to specify a default address for subsequent calls to send-to or receive-from.

remote-host

For TCP streams, it specifies the host to connect to (in any format acceptable to resolve-address). Ignored for listener sockets. For UDP sockets, it can be used to specify a default host for subsequent calls to send-to or receive-from.

remote-port

For TCP streams, it specifies the port to connect to (in any format acceptable to resolve-address). Ignored for listener sockets. For UDP sockets, it can be used to specify a default port for subsequent calls to for subsequent calls to send-to or receive-from.

remote-filename

For file-socket streams, it specifies the name of a file in the local filesystem (e.g., NOT mounted via NFS, AFP, SMB, ...) which names and controls access to a UNIX-domain socket.

local-address

Allows you to specify a local address for a listener or UDP socket, for the case where you want to restrict connections to those coming to a specific local address for security reasons.

local-host

Allows you to specify a local host address for a listener or UDP socket, for the case where you want to restrict connections to those coming to a specific local address for security reasons.

local-port

Specify a local port for a socket. Most useful for listener sockets, where it is the port on which the socket will listen for connections.

local-filename

For file-listener-sockets, specifies the name of a file in the local filesystem which is used to name a UNIX-domain socket. The actual filesystem file should not previously exist when the file-listener-socket is created; its parent directory should exist and be writable by the caller. The file used to name the socket will be deleted when the file-listener-socket is closed.

keepalive

If true, enables the periodic transmission of "keepalive" messages.

reuse-address

If true, allows the reuse of local ports in listener sockets, overriding some TCP/IP protocol specifications. You will need this if you are debugging a server..

nodelay

If true, disables Nagle's algorithm, which tries to minimize TCP packet fragmentation by introducing transmission delays in the absence of replies. Try setting this if you are using a protocol which involves sending a steady stream of data with no replies and are seeing significant degradations in throughput.

broadcast

If true, requests permission to broadcast datagrams on a UDP socket.

linger

If specified and non-nil, should be the number of seconds the OS is allowed to wait for data to be pushed through when a close is done. Only relevant for TCP sockets.

backlog

For a listener socket, specifies the number of connections which can be pending but not accepted. The default is 5, which is also the maximum on some operating systems.

input-timeout

The number of seconds before an input operation times out. Must be a real number between zero and one million. If an input operation takes longer than the specified number of seconds, an input-timeout error is signalled. (see Stream Timeouts and Deadlines)

output-timeout

The number of seconds before an output operation times out. Must be a real number between zero and one million. If an output operation takes longer than the specified number of seconds, an output-timeout error is signalled. (see Stream Timeouts and Deadlines)

connect-timeout

The number of seconds before a connection attempt times out. [TODO: what are acceptable values?] If a connection attempt takes longer than the specified number of seconds, a socket-error is signalled. This can be useful if the specified interval is shorter than the interval that the OS's socket layer imposes, which is sometimes a minute or two.

auto-close

When non-nil, any resulting socket stream will be closed when the GC can prove that the stream is unreferenced. This is done via CCL's termination mechanism [TODO add xref].

deadline

Specifies an absolute time in internal-time-units. If an I/O operation on the stream does not complete before the deadline then a COMMUNICATION-DEADLINE-EXPIRED error is signalled. A deadline takes precedence over any input/output timeouts that may be set. (see Stream Timeouts and Deadlines)

Creates and returns a new socket. For :passive sockets, the :local-address, :local-port or :local-filename arguments are required, depending on the type of the socket. For :active sockets, either the :remote-address, the :remote-host and :remote-port, or the :remote-filename arguments must be present, depending on the socket type.

Extracts the first connection on the queue of pending connections for socket, accepts it (i.e. completes the connection startup protocol), and returns a new tcp-stream or file-socket-stream representing the newly established connection. The tcp stream inherits any properties of the listener socket that are relevant (e.g. :keepalive, :nodelay, and so forth.) The original listener socket continues to be open listening for more connections, so you can call accept-connection on it again.

If :wait is t, and there are no connections waiting to be accepted, the function wait until one arrives. Otherwise, accept-connection will return nil immediately.

Converts a host and/or port specification to one or more ccl::socket-address instances. This function uses the getaddrinfo() system function underneath which knows how to translate all standard address and port formats and appropriately orders addresses for hosts with multiple addresses. It returns the best matching translation or, if the :singlep is false, all matching translations for the given parameter combination.

host

Specification of the host, as a string. This can be either a host name such as “clozure.com” or any of the literal address forms accepted by getaddrinfo().

port

Specification of the port. This can be either a service name such as “http” or a port number.

socket-type

Service type for port lookups, can be either :stream for TCP services or :datagram for UDP. Defaults to :stream.

connect

Specifies how the returned ccl::socket-address instances will be used. If :active is passed, which is the default, the host address will default to the address of the loopback interface of the local host if not specified. When :passive is used, the host address will default to the wildcard address for the given address family. This parameter has no effect if the :host parameter is used.

address-family

Specifies the address family that should be returned, can be specified as either :internet or :internet6. If it is specified, only addresses of that family are returned.

numeric-host-p

If this argument is true, no host name lookups will be performed for the host address. A numeric address literal must be passed in this case.

numeric-port-p

If this argument is true, no service name lookups will be performed for the port address. A numeric port number must be passed in this case.

singlep

If this argument is set to a true value, which is the default, only the first matching address is returned. If it is passed as NIL, all matching addresses are returned as a list.

errorp

If this argument is set to a true value, which is the default, an error is signalled if the given host and/or port combination did not yield any matches. If it is passed as NIL, the function returns NIL if no addresses matched the supplied arguments.

Converts dotted, which should be a dotted quad string such as “192.168.0.1”, into a integer representation. If :errorp is true, an error is signaled if dotted is invalid. Otherwise, nil is returned.

This function converts ipaddr, an integer representing an IPv4 host, into a dotted quad string. If :values is true, instead of a dotted quad string, it returns the four octets of the address as multiple values.

Converts ipaddr, a 32-bit unsigend integer, into a host name string. The keyword argument :ignore-cache is ignored (it is accepted for compatibility with Franz Allegro CL).

Converts host-spec into a 32-bit unsigned IPv4 address. IPv6-enabled applications should use the resolve-address function instead.

Acceptable formats for host-spec include a host name string such as “www.clozure.com”, a dotted address string such as “192.168.0.1”, or a 32-bit unsigned IPv4 address such as 3232235521.

Finds the numeric port number for the specified port and protocol.port can be a string such as “http”, a symbol such as :http, or a port number. Note that strings are case-sensitive. Symbol names are converted to lower-case before lookup. Protocol must be one of “tcp” or “udp”.

Reads a UDP packet from socket. If no packets are available, waits for a packet to arrive.

If :want-socket-address-p is nil, which is the default, four values are returned:

1. The buffer with the data

2. The number of bytes read

3. The 32-bit unsigned IPv4 address or the 16 byte IPv6 address of the sender of the data

4. The port number of the sender of the data

If :want-socket-address-p is true, three values are returned:

1. The buffer with the data

2. The number of bytes read

3. The ccl::socket-address instance of the sender of the data.

socket

The socket to read from

size

Maximum number of bytes to read. If the packet is larger than this, any extra bytes are discarded.

buffer

If specified, must be an octet vector which will be used to read in the data. If not specified, a new buffer will be created (of type determined by socket-format).

extract

If true, the subsequence of the buffer corresponding only to the data read in is extracted and returned as the first value. If false (the default) the original buffer is returned even if it is only partially filled.

offset

Specifies the start offset into the buffer at which data is to be stored. The default is 0.

want-socket-address-p

Indicates that the address of the sender of the data should be returned as a ccl::socket-address instance rather than as separate host and port values.

This function sends a UDP packet over socket.

socket

The socket to write to

buffer

A vector containing the data to send. It must be an octet vector.

size

Number of octets to send

remote

The remote address to send the packet to, as a ccl::socket-address instance. The default is the remote address specified in the call to make-socket.

remote-host

The host to send the packet to, in any format acceptable to lookup-hostname. The default is the remote host specified in the call to make-socket.

remote-port

The port to send the packet to, in any format acceptable to lookup-port. The default is the remote port specified in the call to make-socket.

offset

The offset in the buffer where the packet data starts

Shuts down part of a bidirectional connection represented by socket. Typically socket will be a tcp-stream. One situation where this can be useful is when you need to read responses after sending an end-of-file signal. The keyword argument :direction may be either :input (to disallow further input) or :output (to disallow further output). Or, since release 1.11.5, :both.

Returns the native OS's representation of socket, or nil if the socket is closed. On Unix, this will be a file descriptor. Note that it is rather dangerous to mess around with tcp-stream file descriptors, as there is all sorts of buffering and asynchronous I/O going on above the OS level. listener-socket and udp-socket file descriptors are safer to mess with directly as there is less magic going on.

Returns the 32-bit unsigned IPv4 address of the remote host, or nil if socket is not connected.

Returns the remote port number of socket, or NIL if socket is not connected.

Returns 32-bit unsigned IPv4 address or the 16 byte IPv6 address of the local host for socket.

This function returns the local port number of socket.

Returns :internet, :internet6 or :file, as appropriate for thing, which should be a socket or socket-address.

Returns the host portion of the given socket-address. For :internet addresses, this is a 32-bit integer. For :internet6 addresses, a vector of 16 bytes returned. For :file addresses, it is the file name string.

This function returns the port number of the given socket-address. This function is available only for :internet and :internet6 socket addresses.

This function examines socket and returns :active for a tcp-stream, :passive for listener-socket, and nil for a udp-socket.

Returns the format of socket as specified by the :format argument to make-socket.

This function returns :stream if socket is a tcp-stream or listener-socket. If the socket is a udp-socket, socket-type will return :datagram.

This class is a representation of a socket endpoint address. Instances of this class are used to encapsulate the host and port of an IP socket endpoint or the filename of a file socket. They can be created by applications from a possibly symbolic address representation by the resolve-address function.

The class of OS errors signaled by socket functions (a subclass of simple-error.

Returns the OS error code contained in socket-error.

Returns a symbol representing the socket error code contained in socket-error. It will be one of :address-in-use, :connection-aborted, :no-buffer-space, :connection-timed-out, :connection-refused, :host-unreachable, :host-down, :network-down, :address-not-available, :network-reset, :connection-reset, :shutdown, :access-denied, or :unknown.

Returns a string describing the context where the error socket-error happened. On Linux, this is the name of the system call which returned the error.

Close socket, releasing the operating system resources associated with it. Normally, any pending buffered I/O will be finished up before closing, but if :abort is t, any pending I/O will be aborted. Note that for listener and udp sockets, there is never any buffered I/O to clean up, so the value of :abort is effectively ignored.

Executes body with var bound to the result of applying make-socket to make-socket-args. The socket gets closed on exit.

Returns a fresh list of all lisp processes (threads) known to Clozure CL as of the precise instant it's called. Since other threads can create and kill threads at any time, there's no way to get a perfectly accurate list of all threads.

Creates and returns a new process.

name

a string, used to identify the process.

persistent

if true, requests that information about the process be retained by SAVE-APPLICATION so that an equivalent process can be restarted when a saved image is run. The default is nil.

priority

ignored. It shouldn't be ignored of course, but there are complications on some platforms. The default is 0.

class

the class of process object to create; should be a subclass of CCL:PROCESS. The default is CCL:PROCESS.

initargs

Any additional initargs to pass to MAKE-INSTANCE. The default is ().

stack-size

the size, in bytes, of the newly-created process's control stack; used for foreign function calls and to save function return address context. The default is CCL:*DEFAULT-CONTROL-STACK-SIZE*.

vstack-size

the size, in bytes, of the newly-created process's value stack; used for lisp function arguments, local variables, and other stack-allocated lisp objects. The default is CCL:*DEFAULT-VALUE-STACK-SIZE*.

tstack-size

the size, in bytes, of the newly-created process's temp stack; used for the allocation of dynamic-extent objects. The default is CCL:*DEFAULT-TEMP-STACK-SIZE*.

use-standard-initial-bindings

when true, the global "standard initial bindings" are put into effect in the new thread before. See DEF-STANDARD-INITIAL-BINDING. "standard" initial bindings are put into effect before any bindings specified by :initial-bindings are. The default is t.

This option is deprecated: the correct behavior of many Clozure CL components depends on thread-local bindings of many special variables being in effect.

initial-bindings

an alist of (symbol . valueform) pairs, which can be used to initialize special variable bindings in the new thread. Each valueform is used to compute the value of a new binding of symbol in the execution environment of the newly-created thread. The default is nil.

process

the newly-created process.

Creates and returns a new lisp process (thread) with the specified attributes. process will not begin execution immediately; it will need to be preset (given an initial function to run, as by process-preset) and enabled (allowed to execute, as by process-enable) before it's able to actually do anything.

If valueform is a function, it is called, with no arguments, in the execution environment of the newly-created thread; the primary value it returns is used for the binding of the corresponding symbol.

Otherwise, valueform is evaluated in the execution environment of the newly-created thread, and the resulting value is used.

process-preset, process-enable, process-run-function

Suspends a specified process.

process

a lisp process (thread).

result

T if process had been runnable and is now suspended; NIL otherwise. That is, T if process's process-suspend-count transitioned from 0 to 1.

Suspends process, preventing it from running, and stopping it if it was already running. This is a fairly expensive operation, because it involves a few calls to the OS. It also risks creating deadlock if used improperly, for instance, if the process being suspended owns a lock or other resource which another process will wait for.

Each call to process-suspend must be reversed by a matching call to process-resume before process is able to run. What process-suspend actually does is increment the process-suspend-count of process.

A process can't suspend itself, though this once worked and this documentation claimed has claimed that it did.

process-resume, process-suspend-count

process-suspend was previously called process-disable. process-enable now names a function for which there is no obvious inverse, so process-disable is no longer defined.

Resumes a specified process which had previously been suspended by process-suspend.

process

a lisp process (thread).

result

T if process had been suspended and is now runnable; NIL otherwise. That is, T if process's process-suspend-count transitioned from to 0.

Undoes the effect of a previous call to process-suspend; if all such calls are undone, makes the process runnable. Has no effect if the process is not suspended. What process-resume actually does is decrement the process-suspend-count of process, to a minimum of 0.

process-suspend, process-suspend-count

This was previously called PROCESS-ENABLE; process-enable now does something slightly different.

Returns the number of currently-pending suspensions applicable to a given process.

process

a lisp process (thread).

result

The number of "outstanding" process-suspend calls on process, or NIL if process has expired.

An "outstanding" process-suspend call is one which has not yet been reversed by a call to process-resume. A process expires when its initial function returns, although it may later be reset.

A process is runnable when it has a process-suspend-count of 0, has been preset as by process-preset, and has been enabled as by process-enable. Newly-created processes have a process-suspend-count of 0.

process-suspend, process-resume

Sets the initial function and arguments of a specified process.

process

a lisp process (thread).

function

a function, designated by itself or by a symbol which names it.

args

a list of values, appropriate as arguments to function.

result

undefined.

Typically used to initialize a newly-created or newly-reset process, setting things up so that when process becomes enabled, it will begin execution by applying function to args. process-preset does not enable process, although a process must be process-preset before it can be enabled. Processes are normally enabled by process-enable.

make-process, process-enable, process-run-function

Begins executing the initial function of a specified process.

process

a lisp process (thread).

timeout

a time interval in seconds. May be any non-negative real number the floor of which fits in 32 bits. The default is 1.

result

undefined.

Tries to begin the execution of process. An error is signaled if process has never been process-preset. Otherwise, process invokes its initial function.

process-enable attempts to synchronize with process, which is presumed to be reset or in the act of resetting itself. If this attempt is not successful within the time interval specified by timeout, a continuable error is signaled, which offers the opportunity to continue waiting.

A process cannot meaningfully attempt to enable itself.

make-process, process-preset, process-run-function

It would be nice to have more discussion of what it means to synchronize with the process.

Creates a process, presets it, and enables it.

process-specifier

name | (&key namepersistentpriorityclassinitargsstack-sizevstack-sizetstack-size)

name

a string, used to identify the process. Passed to make-process.

function

a function, designated by itself or by a symbol which names it. Passed to process-preset.

persistent

a boolean, passed to make-process.

priority

ignored.

class

a subclass of CCL:PROCESS. Passed to make-process.

initargs

a list of any additional initargs to pass to make-process.

stack-size

a size, in bytes. Passed to make-process.

vstack-size

a size, in bytes. Passed to make-process.

tstack-size

a size, in bytes. Passed to make-process.

process

the newly-created process.

Creates a lisp process (thread) via make-process, presets it via process-preset, and enables it via process-enable. This means that process will immediately begin to execute. process-run-function is the simplest way to create and run a process.

make-process, process-preset, process-enable

Arranges for the target process to invoke a specified function at some point in the near future, and then return to what it was doing.

process

a lisp process (thread).

function

a function.

args

a list of values, appropriate as arguments to function.

result

the result of applying function to args if process is the *current-process*, otherwise NIL.

Arranges for process to apply function to args at some point in the near future (interrupting whatever process was doing.) If function returns normally, process resumes execution at the point at which it was interrupted.

process must be in an enabled state in order to respond to a process-interrupt request. It's perfectly legal for a process to call process-interrupt on itself.

process-interrupt uses asynchronous POSIX signals to interrupt threads. If the thread being interrupted is executing lisp code, it can respond to the interrupt almost immediately (as soon as it has finished pseudo-atomic operations like consing and stack-frame initialization.)

If the interrupted thread is blocking in a system call, that system call is aborted by the signal and the interrupt is handled on return.

It is still difficult to reliably interrupt arbitrary foreign code (that may be stateful or otherwise non-reentrant); the interrupt request is handled when such foreign code returns to or enters lisp.

without-interrupts

It would probably be better for result to always be NIL, since the present behavior is inconsistent.

process-interrupt works by sending signals between threads, via the C function #_pthread_signal. It could be argued that it should be done in one of several possible other ways under Darwin, to make it practical to asynchronously interrupt things which make heavy use of the Mach nanokernel.

Bound separately in each process, to that process itself. It may be used when lisp code needs to find out what process it is executing in. It should not be set by user code.

This function causes process to cleanly exit from any ongoing computation and enter a state where it can be process-preset.

This is implemented by signaling a condition of type PROCESS-RESET; user-defined condition handlers should generally refrain from attempting to handle conditions of this type.

The kill-option argument is for internal use only and should not be specified by user code.

A process can meaningfully reset itself.

There is in general no way to know precisely when process has completed the act of resetting or killing itself; a process which has either entered the limbo of the reset state or exited has few ways of communicating either fact.

The function process-enable can reliably determine when a process has entered the limbo of the reset state, but can't predict how long the clean exit from ongoing computation might take: that depends on the behavior of unwind-protect cleanup forms, and of the OS scheduler.

Resetting a process other than *current-process* involves the use of the function process-interrupt.

Reset and enable the specified process, which may not be the current process.

process

a lisp process (thread), which may not be the current process.

result

undefined.

Equivalent to calling (process-reset process) and (process-enable process).

process-reset, process-enable

Causes process to cleanly exit from any ongoing computation, and then exit. Note that unwind-protect cleanup forms will be run with interrupts disabled.

Causes a specified process to process an abort condition, as if it had invoked abort.

process

a lisp process (thread).

condition

a lisp condition. The default is NIL.

Entirely equivalent to calling (process-interruptprocess (lambda () (abortcondition))). Causes process to transfer control to the applicable handler or restart for abort.

If condition is non-NIL, process-abort does not consider any handlers which are explicitly bound to conditions other than condition.

process-reset, process-kill

Bound to the clock resolution of the OS scheduler.

A positive integer.

The clock resolution of the OS scheduler. Currently, both LinuxPPC and DarwinPPC yield an initial value of 100.

This value is ordinarily of marginal interest at best, but, for backward compatibility, some functions accept timeout values expressed in "ticks". This value gives the number of ticks per second.

process-wait-with-timeout

Returns a string which describes the status of a specified process.

process

a lisp process (thread).

whostate

a string which describes the "state" of process.

This information is primarily for the benefit of debugging tools. whostate is a terse report on what process is doing, or not doing, and why.

If the process is currently waiting in a call to process-wait or process-wait-with-timeout, its process-whostate will be the value which was passed to that function as whostate.

process-wait, process-wait-with-timeout, with-terminal-input

This should arguably be SETFable, but doesn't seem to ever have been.

Used for cooperative multitasking; probably never necessary.

Advises the OS scheduler that the current thread has nothing useful to do and that it should try to find some other thread to schedule in its place. There's almost always a better alternative, such as waiting for some specific event to occur. For example, you could use a lock or semaphore.

make-lock, make-read-write-lock, make-semaphore, process-input-wait, process-output-wait, with-terminal-input

This is a holdover from the days of cooperative multitasking. All modern general-purpose operating systems use preemptive multitasking.

Causes the current lisp process (thread) to wait for a given predicate to return true.

whostate

a string, which will be the value of process-whostate while the process is waiting.

function

a function, designated by itself or by a symbol which names it.

args

a list of values, appropriate as arguments to function.

result

NIL.

Causes the current lisp process (thread) to repeatedly apply function to args until the call returns a true result, then returns NIL. After each failed call, yields the CPU as if by process-allow-schedule.

As with process-allow-schedule, it's almost always more efficient to wait for some specific event to occur; this isn't exactly busy-waiting, but the OS scheduler can do a better job of scheduling if it's given the relevant information. For example, you could use a lock or semaphore.

process-whostate, process-wait-with-timeout, make-lock, make-read-write-lock, make-semaphore, process-input-wait, process-output-wait, with-terminal-input

Causes the current thread to wait for a given predicate to return true, or for a timeout to expire.

whostate

a string, which will be the value of process-whostate while the process is waiting.

ticks

either a positive integer expressing a duration in "ticks" (see *ticks-per-second*), or NIL.

function

a function, designated by itself or by a symbol which names it.

args

a list of values, appropriate as arguments to function.

result

T if process-wait-with-timeout returned because its function returned true, or NIL if it returned because the duration ticks has been exceeded.

If ticks is NIL, behaves exactly like process-wait, except for returning T. Otherwise, function will be tested repeatedly, in the same kind of test/yield loop as in process-wait until either function returns true, or the duration ticks has been exceeded.

Having already read the descriptions of process-allow-schedule and process-wait, the astute reader has no doubt anticipated the observation that better alternatives should be used whenever possible.

*ticks-per-second*, process-whostate, process-wait, make-lock, make-read-write-lock, make-semaphore, process-input-wait, process-output-wait, with-terminal-input

Evaluates its body in an environment in which process-interrupt requests are deferred.

body

an implicit progn.

result

the primary value returned by body.

Executes body in an environment in which process-interrupt requests are deferred. As noted in the description of process-interrupt, this has nothing to do with the scheduling of other threads; it may be necessary to inhibit process-interrupt handling when (for instance) modifying some data structure (for which the current thread holds an appropriate lock) in some manner that's not reentrant.

process-interrupt

Evaluates its body in an environment in which process-interrupt requests have immediate effect.

body

an implicit progn.

result

the primary value returned by body.

Executes body in an environment in which process-interrupt requests have immediate effect.

Creates and returns a lock object, which can be used for synchronization between threads.

name

any lisp object; saved as part of lock. Typically a string or symbol which may appear in the process-whostates of threads which are waiting for lock.

lock

a newly-allocated object of type CCL:LOCK.

Creates and returns a lock object, which can be used to synchronize access to some shared resource. lock is initially in a "free" state; a lock can also be "owned" by a thread.

with-lock-grabbed, grab-lock, release-lock, try-lock, make-read-write-lock, make-semaphore, process-input-wait, process-output-wait, with-terminal-input

Waits until a given lock can be obtained, then evaluates its body with the lock held.

lock

an object of type CCL:LOCK.

body

an implicit progn.

result

the primary value returned by body.

Waits until lock is either free or owned by the calling thread, then executes body with the lock owned by the calling thread. If lock was free when with-lock-grabbed was called, it is restored to a free state after body is executed.

make-lock, grab-lock, release-lock, try-lock, make-read-write-lock, make-semaphore, process-input-wait, process-output-wait, with-terminal-input

Waits until a given lock can be obtained, then obtains it.

lock

an object of type CCL:LOCK.

Blocks until lock is owned by the calling thread.

The macro with-lock-grabbedcould be defined in terms of grab-lock and release-lock, but it is actually implemented at a slightly lower level.

make-lock, with-lock-grabbed, release-lock, try-lock, make-read-write-lock, make-semaphore, process-input-wait, process-output-wait, with-terminal-input

Relinquishes ownership of a given lock.

lock

an object of type CCL:LOCK.

Signals an error of type CCL:LOCK-NOT-OWNER if lock is not already owned by the calling thread; otherwise, undoes the effect of one previous grab-lock. If this means that release-lock has now been called on lock the same number of times as grab-lock has, lock becomes free.

make-lock, with-lock-grabbed, grab-lock, try-lock, make-read-write-lock, make-semaphore, process-input-wait, process-output-wait, with-terminal-input

Obtains the given lock, but only if it is not necessary to wait for it.

lock

an object of type CCL:LOCK.

result

T if lock has been obtained, or NIL if it has not.

Tests whether lock can be obtained without blocking - that is, either lock is already free, or it is already owned by *current-process*. If it can, causes it to be owned by the calling lisp process (thread) and returns T. Otherwise, the lock is already owned by another thread and cannot be obtained without blocking; NIL is returned in this case.

make-lock, with-lock-grabbed, grab-lock, release-lock, make-read-write-lock, make-semaphore, process-input-wait, process-output-wait, with-terminal-input

Creates and returns a read-write lock, which can be used for synchronization between threads.

read-write-lock

a newly-allocated object of type CCL:READ-WRITE-LOCK.

Creates and returns an object of type CCL::READ-WRITE-LOCK. A read-write lock may, at any given time, belong to any number of lisp processes (threads) which act as "readers"; or, it may belong to at most one process which acts as a "writer". A read-write lock may never be held by a reader at the same time as a writer. Initially, read-write-lock has no readers and no writers.

with-read-lock, with-write-lock, make-lock, make-semaphore, process-input-wait, process-output-wait, with-terminal-input

There probably should be some way to atomically "promote" a reader, making it a writer without releasing the lock, which could otherwise cause delay.

Waits until a given lock is available for read-only access, then evaluates its body with the lock held.

read-write-lock

an object of type CCL:READ-WRITE-LOCK.

body

an implicit progn.

result

the primary value returned by body.

Waits until read-write-lock has no writer, ensures that *current-process* is a reader of it, then executes body.

After executing body, if *current-process* was not a reader of read-write-lock before with-read-lock was called, the lock is released. If it was already a reader, it remains one.

make-read-write-lock, with-write-lock, make-lock, make-semaphore, process-input-wait, process-output-wait, with-terminal-input

Waits until the given lock is available for write access, then executes its body with the lock held.

read-write-lock

an object of type CCL:READ-WRITE-LOCK.

body

an implicit progn.

result

the primary value returned by body.

Waits until read-write-lock has no readers and no writer other than *current-process*, then ensures that *current-process* is the writer of it. With the lock held, executes body.

After executing body, if *current-process* was not the writer of read-write-lock before with-write-lock was called, the lock is released. If it was already the writer, it remains the writer.

make-read-write-lock, with-read-lock, make-lock, make-semaphore, process-input-wait, process-output-wait, with-terminal-input

Creates and returns a semaphore, which can be used for synchronization between threads.

semaphore

a newly-allocated object of type CCL:SEMAPHORE.

Creates and returns an object of type CCL:SEMAPHORE. A semaphore has an associated "count" which may be incremented and decremented atomically; incrementing it represents sending a signal, and decrementing it represents handling that signal. semaphore has an initial count of 0.

signal-semaphore, wait-on-semaphore, timed-wait-on-semaphore, make-lock, make-read-write-lock, process-input-wait, process-output-wait, with-terminal-input

Atomically increments the count of a given semaphore.

semaphore

an object of type CCL:SEMAPHORE.

result

an integer representing an error identifier which was returned by the underlying OS call.

Atomically increments semaphore's "count" by 1; this may enable a waiting thread to resume execution.

make-semaphore, wait-on-semaphore, timed-wait-on-semaphore, make-lock, make-read-write-lock, process-input-wait, process-output-wait, with-terminal-input

result should probably be interpreted and acted on by signal-semaphore, because it is not likely to be meaningful to a lisp program, and the most common cause of failure is a type error.

Waits until the given semaphore has a positive count which can be atomically decremented.

semaphore

an object of type CCL:SEMAPHORE.

result

an integer representing an error identifier which was returned by the underlying OS call.

Waits until semaphore has a positive count that can be atomically decremented; this will succeed exactly once for each corresponding call to SIGNAL-SEMAPHORE.

make-semaphore, signal-semaphore, timed-wait-on-semaphore, make-lock, make-read-write-lock, process-input-wait, process-output-wait, with-terminal-input

result should probably be interpreted and acted on by wait-on-semaphore, because it is not likely to be meaningful to a lisp program, and the most common cause of failure is a type error.

Waits until the given semaphore has a positive count which can be atomically decremented, or until a timeout expires.

semaphore

An object of type CCL:SEMAPHORE.

timeout

a time interval in seconds. May be any non-negative real number the floor of which fits in 32 bits. The default is 1.

result

T if timed-wait-on-semaphore returned because it was able to decrement the count of semaphore; NIL if it returned because the duration timeout has been exceeded.

Waits until semaphore has a positive count that can be atomically decremented, or until the duration timeout has elapsed.

make-semaphore, wait-on-semaphore, make-lock, make-read-write-lock, process-input-wait, process-output-wait, with-terminal-input

Waits until input is available on a given file-descriptor.

fd

a file descriptor, which is a non-negative integer used by the OS to refer to an open file, socket, or similar I/O connection. See stream-device.

timeout

either NIL or a time interval in milliseconds. Must be a non-negative integer. The default is NIL.

Wait until input is available on fd. This uses the select() system call, and is generally a fairly efficient way of blocking while waiting for input. More accurately, process-input-wait waits until it's possible to read from fd without blocking, or until timeout, if it is not NIL, has been exceeded.

Note that it's possible to read without blocking if the file is at its end - although, of course, the read will return zero bytes.

make-lock, make-read-write-lock, make-semaphore, process-output-wait, with-terminal-input

process-input-wait has a timeout parameter, and process-output-wait does not. This inconsistency should probably be corrected.

Waits until output is possible on a given file descriptor.

fd

a file descriptor, which is a non-negative integer used by the OS to refer to an open file, socket, or similar I/O connection. See stream-device.

timeout

either NIL or a time interval in milliseconds. Must be a non-negative integer. The default is NIL.

Wait until output is possible on fd or until timeout, if it is not NIL, has been exceeded. This uses the select() system call, and is generally a fairly efficient way of blocking while waiting to output.

If process-output-wait is called on a network socket which has not yet established a connection, it will wait until the connection is established. This is an important use, often overlooked.

make-lock, make-read-write-lock, make-semaphore, process-input-wait, with-terminal-input

process-input-wait has a timeout parameter, and process-output-wait does not. This inconsistency should probably be corrected.

Executes its body in an environment with exclusive read access to the terminal.

body

an implicit progn.

result

the primary value returned by body.

Requests exclusive read access to the standard terminal stream, *terminal-io*. Executes body in an environment with that access.

*request-terminal-input-via-break*, ":Y", make-lock, make-read-write-lock, make-semaphore, process-input-wait, process-output-wait

Controls how attempts to obtain ownership of terminal input are made.

A boolean.

NIL.

Controls how attempts to obtain ownership of terminal input are made. When NIL, a message is printed on *TERMINAL-IO*; it's expected that the user will later yield control of the terminal via the :Y toplevel command. When T, a BREAK condition is signaled in the owning process; continuing from the break loop will yield the terminal to the requesting process (unless the :Y command was already used to do so in the break loop.)

with-terminal-input, ":Y", make-lock, make-read-write-lock, make-semaphore, process-input-wait, process-output-wait

Yields control of terminal input to a specified lisp process (thread).

p

a lisp process (thread), designated either by an integer which matches its process-serial-number, or by a string which is equal to its process-name.

:Y is a toplevel command, not a function. As such, it can only be used interactively, and only from the initial process.

The command yields control of terminal input to the process p, which must have used with-terminal-input to request access to the terminal input stream.

with-terminal-input, *request-terminal-input-via-break*, make-lock, make-read-write-lock, make-semaphore, process-input-wait, process-output-wait

Waits for a specified process to complete and returns the values that that process's initial function returned.

process

a process, typically created by process-run-function or by make-process

default

A default value to be returned if the specified process doesn't exit normally.

values

The values returned by the specified process's initial function if that function returns, or the value of the default argument, otherwise.

Waits for the specified process to terminate. If the process terminates "normally" (if its initial function returns), returns the values that that initial function returns. If the process does not terminate normally (e.g., if it's terminated via process-kill and a default argument is provided, returns the value of that default argument. If the process doesn't terminate normally and no default argument is provided, signals an error.

A process can't successfully join itself, and only one process can successfully receive notification of another process's termination.

Reads a symbol from the current input stream, with *PACKAGE* bound to the "OS" package and with readtable-case preserved.

Does a lookup on that symbol in the Clozure CL interface database, signalling an error if no foreign function information can be found for the symbol in any active interface directory.

Notes the foreign function information, including the foreign function's return type, the number and type of the foreign function's required arguments, and an indication of whether or not the function accepts additional arguments (via e.g., the "varargs" mechanism in C).

Defines a macroexpansion function on the symbol, which expand macro calls involving the symbol into EXTERNAL-CALL forms where foreign argument type specifiers for required arguments and the return value specifier are provided from the information in the database.

Returns the symbol.

The effect of these steps is that it's possible to call foreign functions that take fixed numbers of arguments by simply providing argument values, as in:

(#_isatty fd)
          (#_read fd buf n)

and to call foreign functions that take variable numbers of arguments by specifying the types of non-required args, as in:

(with-cstrs ((format-string "the answer is: %d"))
          (#_printf format-string :int answer))

You can query whether a given name is defined in the interface databases by appending the '?' character to the reader macro; for example:

          CL-USER> #_?printf
          T
          CL-USER> #_?foo
          NIL
        

In Clozure CL 1.2 and later, the #& reader macro can be used to access foreign variables; this functionality depends on the presence of "vars.cdb" files in the interface database. The current behavior of the #& reader macro is to:

Read a symbol from the current input stream, with *PACKAGE* bound to the "OS" package and with readtable-case preserved.

Use that symbol's pname to access the Clozure CL interface database, signalling an error if no appropriate foreign variable information can be found with that name in any active interface directory.

Use type information recorded in the database to construct a form which can be used to access the foreign variable, and return that form.

Please note that the set of foreign variables declared in header files may or may not match the set of foreign variables exported from libraries (we're generally talking about C and Unix here ...). When they do match, the form constructed by the #& reader macro manages the details of resolving and tracking changes to the foreign variable's address.

Future extensions (via prefix arguments to the reader macro) may offer additional behavior; it might be convenient (for instance) to be able to access the address of a foreign variable without dereferencing that address.

Foreign variables in C code tend to be platform- and package-specific (the canonical example - "errno" - is typically not a variable when threads are involved. )

In LinuxPPC,

? #&stderr

returns a pointer to the stdio error stream ("stderr" is a macro under OSX/Darwin).

On both LinuxPPC and DarwinPPC,

? #&sys_errlist

returns a pointer to a C array of C error message strings.

You can query whether a given name is defined in the interface databases by appending the '?' character to the reader macro; for example:

          CL-USER> #&?sys_errlist
          T
          CL-USER> #&?foo
          NIL
        

In Clozure CL 0.14.2 and later, the #? reader macro can be used to access foreign constants; this functionality depends on the presence of "constants.cdb" files in the interface database. The current behavior of the #$ reader macro is to:

Read a symbol from the current input stream, with *PACKAGE* bound to the "OS" package and with readtable-case preserved.

Use that symbol's pname to access the Clozure CL interface database, signalling an error if no appropriate foreign constant information can be found with that name in any active interface directory.

Use type information recorded in the database to construct a form which can be used to access the foreign constant, and return that form.

Please note that the set of foreign constants declared in header files may or may not match the set of foreign constants exported from libraries. When they do match, the form constructed by the #$ reader macro manages the details of resolving and tracking changes to the foreign constant's address.

You can query whether a given name is defined in the interface databases by appending the '?' character to the reader macro; for example:

          CL-USER> #$?SO_KEEPALIVE
          T
          CL-USER> #$?foo
          NIL
        

In Clozure CL 1.2 and later, the #/ reader macro can be used to access foreign functions on the Darwin platform. The current behavior of the #/ reader macro is to:

Read a symbol from the current input stream, with *PACKAGE* bound to the "NEXTSTEP-FUNCTIONS" package, with readtable-case preserved, and with any colons included.

Do limited sanity-checking on the resulting symbol; for example, any name that contains at least one colon is required also to end with a colon, to conform to Objective-C method-naming conventions.

Export the resulting symbol from the "NEXTSTEP-FUNCTIONS" package and return it.

For example, reading "#/alloc" interns and returns NEXTSTEP-FUNCTIONS:|alloc|. Reading "#/initWithFrame:" interns and returns NEXTSTEP-FUNCTIONS:|initWithFrame:|.

A symbol read using this macro can be used as an operand in most places where an Objective-C message name can be used, such as in the (OBJ:@SELECTOR ...) construct.

Please note: the reader macro is not rigorous about enforcing Objective-C method-naming conventions. Despite the simple checking done by the reader macro, it may still be possible to use it to construct invalid names.

The act of interning a new symbol in the NEXTSTEP-FUNCTIONS package triggers an interface database lookup of Objective-C methods with the corresponding message name. If any such information is found, a special type of dispatching function is created and initialized and the new symbol is given the newly-created dispatching function as its function definition.

The dispatching knows how to call declared Objective-C methods defined on the message. In many cases, all methods have the same foreign type signature, and the dispatching function merely passes any arguments that it receives to a function that does an Objective-C message send with the indicated foreign argument and return types. In other cases, where different Objective-C messages have different type signatures, the dispatching function tries to choose a function that handles the right type signature based on the class of the dispatching function's first argument.

If new information about Objective-C methods is introduced (e.g., by using additional interface files or as Objective-C methods are defined from lisp), the dispatch function is reinitialized to recognize newly-introduced foreign type signatures.

The argument and result coercion that the bridge has traditionally supported is supported by the new mechanism (e.g., :<BOOL> arguments can be specified as lisp booleans and :<BOOL> results are returned as lisp boolean values, and an argument value of NIL is coerced to a null pointer if the corresponding argument type is :ID.

Some Objective-C methods accept variable numbers of arguments; the foreign types of non-required arguments are determined by the lisp types of those arguments (e.g., integers are passed as integers, floats as floats, pointers as pointers, record types by reference.)

Examples:

          ;;; #/alloc is a known message.
          ? #'#/alloc
          #<OBJC-DISPATCH-FUNCTION NEXTSTEP-FUNCTIONS:|alloc| #x300040E94EBF>
          ;;; Sadly, #/foo is not ...
          ? #'#/foo
          > Error: Undefined function: NEXTSTEP-FUNCTIONS:|foo|
          ;;; We can send an "init" message to a newly-allocated instance of
          ;;; "NSObject" by:
          (send (send ns:ns-object 'alloc) 'init)
          ;;; or by
          (#/init (#/alloc ns:ns-object))
        

Objective-C methods that "return" structures return them as garbage-collectable pointers when called via dispatch functions. For example, if "my-window" is an NS:NS-WINDOW instance, then

          (#/frame my-window)
        

returns a garbage-collectable pointer to a structure that describes that window's frame rectangle. This convention means that there's no need to use SLET or special structure-returning message send syntax; keep in mind, though, that #_malloc, #_free, and the GC are all involved in the creation and eventual destruction of structure-typed return values. In some programs these operations may have an impact on performance.

In Clozure CL 1.2 and later, the #> reader macro reads the following text as a keyword, preserving the case of the text. For example:

          CL-USER> #>FooBar
          :<F>OO<B>AR
        

The resulting keyword can be used as the name of foreign types, records, and accessors.

Stops using a shared library, informing the operating system that it can be unloaded if appropriate.

library

either an object of type SHLIB, or a string which designates one by its so-name.

completely

a boolean. The default is T.

If completely is T, sets the reference count of library to 0. Otherwise, decrements it by 1. In either case, if the reference count becomes 0, close-shared-library frees all memory resources consumed library and causes any EXTERNAL-ENTRY-POINTs known to be defined by it to become unresolved.

Proclaims name to be a special variable; sets its value to a MACPTR which, when called by foreign code, calls a lisp function which expects foreign arguments of the specified types and which returns a foreign value of the specified result type. Any argument variables which correspond to foreign arguments of type :ADDRESS are bound to stack-allocated MACPTRs.

If name is already a callback function pointer, its value is not changed; instead, it's arranged that an updated version of the lisp callback function will be called. This feature allows for callback functions to be redefined incrementally, just like Lisp functions are.

defcallback returns the callback pointer, e.g., the value of name.

name

A symbol which can be made into a special variable

arg-type-specifier

One of the foreign argument-type keywords, described above, or an equivalent foreign type specifier. In addition, if the keyword :WITHOUT-INTERRUPTS is specified, the callback will be executed with lisp interrupts disabled if the corresponding var is non-NIL. If :WITHOUT-INTERRUPTS is specified more than once, the rightmost instance wins.

var

A symbol (lisp variable), which will be bound to a value of the specified type.

body

A sequence of lisp forms, which should return a value which can be coerced to the specified result-type.

If name is non-nil, defines name to be an alias for the foreign type specified by foreign-type-spec. If foreign-type-spec is a named structure or union type, additionally defines that structure or union type.

If name is nil, foreign-type-spec must be a named foreign struct or union definition, in which case the foreign structure or union definition is put in effect.

Note that there are two separate namespaces for foreign type names: one for the names of ordinary types and one for the names of structs and unions. Which one name refers to depends on foreign-type-spec in the obvious manner.

name

NIL or a keyword; the keyword may contain escaping constructs.

foreign-type-spec

A foreign type specifier, whose syntax is (loosely) defined above.

Resolves a reference to an external symbol which is defined in a shared library.

name

a simple-string which names an external symbol. Case-sensitive.

entry

an object of type EXTERNAL-ENTRY-POINT which maintains the address of the foreign symbol named by name.

If there is already an EXTERNAL-ENTRY-POINT for the symbol named by name, finds it and returns it. If not, creates one and returns it.

Tries to resolve the entry point to a memory address, and identify the containing library.

Be aware that under Darwin, external functions which are callable from C have underscores prepended to their names, as in "_fopen".

Calls the foreign function at the address obtained by resolving the external-entry-point associated with name, passing the values of each arg as a foreign argument of type indicated by the corresponding arg-type-specifier. Returns the foreign function result (coerced to a Lisp object of type indicated by result-type-specifier), or NIL if result-type-specifier is :VOID or NIL

name

A lisp string. See external, above.

arg-type-specifer

One of the foreign argument-type keywords, described above, or an equivalent foreign type specifier.

arg

A lisp value of type indicated by the corresponding arg-type-specifier

result-type-specifier

One of the foreign argument-type keywords, described above, or an equivalent foreign type specifier.

This is the most fundamental and lowest-level way to call a foreign function. It calls the foreign function at address entrypoint passing the values of each arg as a foreign argument of type indicated by the corresponding arg-type-keyword. Returns the foreign function result (coerced to a Lisp object of type indicated by result-type-keyword), or nil if result-type-keyword is :void or NIL.

entrypoint

A fixnum or macptr

arg-type-keyword

One of the foreign argument-type keywords, described above

arg

A lisp value of type indicated by the corresponding arg-type-keyword

result-type-keyword

One of the foreign argument-type keywords, described above

Calls the foreign function at address entrypoint passing the values of each arg as a foreign argument of type indicated by the corresponding arg-type-specifier. Returns the foreign function result (coerced to a Lisp object of type indicated by result-type-specifier), or NIL if result-type-specifier is :VOID or NIL

entrypoint

A fixnum or MACPTR

arg-type-specifer

One of the foreign argument-type keywords, described above, or an equivalent foreign type specifier.

arg

A lisp value of type indicated by the corresponding arg-type-specifier

result-type-specifier

One of the foreign argument-type keywords, described above, or an equivalent foreign type specifier.

This function tries to resolve the address of the foreign symbol name (a lisp string). If successful, it returns that address encapsulated in a macptr; otherwise, it returns nil.

This function tries to resolve the address of the foreign symbol name (a lisp string). If successful, it returns a fixnum representation of that address. Otherwise, it returns nil.

Free the foreign memory pointed to by ptr by invoking the standard C function free(). If ptr is a gcable pointer (such as an object returned from ccl::make-gcable-record), then free first informs the garbage collector that the foreign memory has been deallocated before actually calling free().

An ivector is a one-dimensional array that's specialized to a numeric or character element type.

make-heap-ivector allocates an ivector in foreign memory. The GC will never move this vector, and will in fact not pay any attention to it at all. The returned pointer to it can therefore be passed safely to foreign code.

The vector must be explicitly deallocated with dispose-heap-ivector.

element-count

A positive integer.

element-type

A type specifier.

vector

A lisp vector. The initial contents are undefined.

mactpr

A pointer to the first byte of data stored in the vector.

size

The size of the returned vector in octets.

Allocates a block of foreign memory suitable to hold the foreign type described by typespec, in the same manner as make-record. In addition, ccl::make-gcable-record marks the returned object gcable: in other words, it informs the garbage collector that it may reclaim the object when it becomes unreachable.

In all other respects, ccl::make-gcable-record works the same way as make-record.

When using gcable pointers, it's important to remember the distinction between a macptr object (which is a lisp object, more or less like any other) and the block of foreign memory that the macptr object points to. If a gcable macptr object is the only thing in the world (lisp world or foreign world) that references the underlying block of foreign memory, then freeing the foreign memory when it becomes impossible to reference it is convenient and sane. If other lisp macptrs reference the underlying block of foreign memory or if the address of that foreign memory is passed to and retained by foreign code, having the GC free the memory may have unpleasant consequences if those other references are used.

Take care, therefore, not to create a gcable record unless you are sure that the returned macptr will be the only reference to the allocated memory that will ever be used.

typespec

A foreign type specifier, or a keyword which is used as the name of a foreign struct or union.

initforms

If the type denoted by typespec is scalar, a single value appropriate for that type; otherwise, a list of alternating field names and values appropriate for the types of those fields.

result

A macptr which encapsulates the address of a newly-allocated record on the foreign heap. The foreign object returned by ccl::make-gcable-record is freed when the garbage collector determines that the MACPTR object that describes it is unreachable.

Expands into code which allocates and initializes an instance of the type denoted by typespec, on the foreign heap. The record is allocated using the C function ccl::malloc, and the user of make-record must explicitly call the function free to deallocate the record, when it is no longer needed.

If initforms is provided, its value or values are used in the initialization. When the type is a scalar, initforms is either a single value which can be coerced to that type, or no value, in which case binary 0 is used. When the type is a struct, initforms is a list, giving field names and the values for each. Each field is treated in the same way as a scalar is: If a value for it is given, it must be coerceable to the field's type; if not, binary 0 is used.

When the type is an array, initforms may not be provided, because make-record cannot initialize its values. make-record is also unable to initialize fields of a struct which are themselves structs. The user of make-record should set these values by another means.

A possibly-significant limitation is that it must be possible to find the foreign type at the time the macro is expanded; make-record signals an error if this is not the case.

typespec

A foreign type specifier, or a keyword which is used as the name of a foreign struct or union.

initforms

If the type denoted by typespec is scalar, a single value appropriate for that type; otherwise, a list of alternating field names and values appropriate for the types of those fields.

result

A macptr which encapsulates the address of a newly-allocated record on the foreign heap.

It is inconvenient that make-record is a macro, because this means that typespec cannot be a variable; it must be an immediate value.

If it weren't for this requirement, make-record could be a function. However, that would mean that any stand-alone application using it would have to include a copy of the interface database (see The Interface Database), which is undesirable because it's large.

Asks the operating system to load a shared library for Clozure CL to use.

name

A SIMPLE-STRING which is presumed to be the so-name of or a filesystem path to the library.

library

An object of type SHLIB which describes the library denoted by name.

If the library denoted by name can be loaded by the operating system, returns an object of type SHLIB that describes the library; if the library is already open, increments a reference count. If the library can't be loaded, signals a SIMPLE-ERROR which contains an often-cryptic message from the operating system.

;;; Try to do something simple.
          ? (open-shared-library "libgtk.so")
          > Error: Error opening shared library "libgtk.so": /usr/lib/libgtk.so: undefined symbol: gdk_threads_mutex
          > While executing: OPEN-SHARED-LIBRARY
          ;;; Grovel around, curse, and try to find out where "gdk_threads_mutex"
          ;;; might be defined. Then try again:
          ? (open-shared-library "libgdk.so")
          #<SHLIB libgdk.so #x3046DBB6>
          ? (open-shared-library "libgtk.so")
          #<SHLIB libgtk.so #x3046DC86>
          ;;; Reference an external symbol defined in one of those libraries.
          ? (external "gtk_main")
          #<EXTERNAL-ENTRY-POINT "gtk_main" (#x012C3004) libgtk.so #x3046FE46>
          ;;; Close those libraries.
          ? (close-shared-library "libgtk.so")
          T
          ? (close-shared-library "libgdk.so")
          T
          ;;; Reference the external symbol again.
          ? (external "gtk_main")
          #<EXTERNAL-ENTRY-POINT "gtk_main" {unresolved} libgtk.so #x3046FE46>

It would be helpful to describe what an soname is and give examples of one.

Does the SHLIB still get returned if the library is already open?

References an instance of a foreign type (or a component of a foreign type) accessible via ptr.

Expands into code which references the indicated scalar type or component, or returns a pointer to a composite type.

PREF can be used with SETF.

ptr

a MACPTR.

accessor-form

a keyword which names a foreign type or record, as described in Foreign type, record, and field names.

Tries to resolve the address of the external-entry-point eep and returns a fixnum representation of that address if successful; else signals an error.

eep

An EXTERNAL-ENTRY-POINT, as obtained by the EXTERNAL macro.

Executes body in an environment in which each var is bound to a macptr encapsulating the address of a stack-allocated foreign memory block, allocated and initialized from typespec and initforms as permake-record. Returns whatever values body returns.

Record fields that aren't explicitly initialized have unspecified contents.

var

A symbol (a lisp variable)

typespec

A foreign type specifier or foreign record name.

initforms

As described above, for make-record

This macro is just like rlet, except that the stack-allocated foreign memory is zeroed.

The termination mechanism is a way to have the garbage collector run a function right before an object is about to become garbage. It is very similar to the finalization mechanism which Java has. It is not standard Common Lisp, although other Lisp implementations have similar features. It is useful when there is some sort of special cleanup, deallocation, or releasing of resources which needs to happen when a certain object is no longer being used.

When the garbage collector discovers that an object is no longer referred to anywhere in the program, it deallocates that object, freeing its memory. However, if terminate-when-unreachable has been called on the object at any time, the garbage collector first invokes the generic function terminate, passing it the object as a parameter.

Therefore, to make termination do something useful, you need to define a method on terminate.

Because calling terminate-when-unreachable only affects a single object, rather than all objects of its class, you may wish to put a call to it in the initialize-instance method of a class. Of course, this is only appropriate if you do in fact want to use termination for all objects of a given class.

object

A CLOS object of a class for which there exists a method of the generic function terminate.

          (defclass resource-wrapper ()
            ((resource :accessor resource)))
          (defmethod initialize-instance :after ((x resource-wrapper) &rest initargs)
             (ccl:terminate-when-unreachable x))
          (defmethod ccl:terminate ((x resource-wrapper))
             (when (resource x)
                (deallocate (resource x))))

Tutorial: Allocating Foreign Data on the Lisp Heap

Tells Clozure CL to remove the interface directory denoted by dir-id from the list of interface directories which are consulted for foreign type and function information. Returns T if the directory was on the search list, NIL otherwise.

dir-id

A keyword whose pname, mapped to lower case, names a subdirectory of "ccl:headers;" (or "ccl:darwin-headers;")

Tells Clozure CL to add the interface directory denoted by dir-id to the list of interface directories which it consults for foreign type and function information. Arranges that that directory is searched before any others.

Note that use-interface-dir merely adds an entry to a search list. If the named directory doesn't exist in the file system or doesn't contain a set of database files, a runtime error may occur when Clozure CL tries to open some database file in that directory, and it will try to open such a database file whenever it needs to find any foreign type or function information. unuse-interface-dir may come in handy in that case.

dir-id

A keyword whose pname, mapped to lower case, names a subdirectory of "ccl:headers;" (or "ccl:darwin-headers;")

One typically wants interface information to be available at compile-time (or, in many cases, at read-time). A typical idiom would be:

(eval-when (:compile-toplevel :execute)
          (use-interface-dir :GTK))

Using the :GTK interface directory makes available information on foreign types, functions, and constants. It's generally necessary to load foreign libraries before actually calling the foreign code, which for GTK can be done like this:

(load-gtk-libraries)

It should now be possible to do things like:

(#_gtk_widget_destroy w)

Invokes an external program as an OS subprocess of lisp.

program

A string or pathname which denotes an executable file. The PATH environment variable is used to find programs whose name doesn't contain a directory component.

args

A list of simple-strings

wait

Indicates whether or not run-program should wait for the EXTERNAL-PROCESS to complete or should return immediately.

pty

This option is accepted but currently ignored; it's intended to make it easier to run external programs that need to interact with a terminal device.

sharing

Sets a specific sharing mode (see Additional keywords for OPEN and MAKE-SOCKET) for any streams created within RUN-PROGRAM when INPUT, OUTPUT or ERROR are requested to be a :STREAM.

input

Selects the input source used by the EXTERNAL-PROCESS. May be any of the following:

• NIL Specifies that a null input stream (e.g., /dev/null) should be used.

• T Specifies that the EXTERNAL-PROCESS should use the input source with which Clozure CL was invoked.

• A string or pathname. Specifies that the EXTERNAL-PROCESS should receive its input from the named existing file.

• :STREAM Creates a Lisp stream opened for character output. Any data written to this stream (accessible as the EXTERNAL-PROCESS-INPUT-STREAM of the EXTERNAL-PROCESS object) appears as input to the external process.

• A stream. Specifies that the lisp stream should provide input to the EXTERNAL-PROCESS.

if-input-does-not-exist

If the input argument specifies the name of an existing file, this argument is used as the if-does-not-exist argument to OPEN when that file is opened.

output

Specifies where standard output from the external process should be sent. Analogous to input above.

if-output-exists

If output is specified as a string or pathname, this argument is used as the if-exists argument to OPEN when that file is opened.

error

Specifies where error output from the external process should be sent. In addition to the values allowed for output, the keyword :OUTPUT can be used to indicate that error output should be sent where standard output goes.

if-error-exists

Analogous to if-output-exists.

status-hook

A user-defined function of one argument (the EXTERNAL-PROCESS structure.) This function is called whenever Clozure CL detects a change in the status of the EXTERNAL-PROCESS.

external-format

The external format (see External Formats) for all of the streams (input, output, and error) used to communicate with the external process.

env

New OS environment variable bindings for the external process. By default the external process inherits the environment of the running Lisp process. Env is an association list with elements (<Environment Variable Name> . <Value>). Name and value are case sensitive strings. See setenv.

silently-ignore-catastrophic-failures

If NIL, signal an error if run-program is unable to start the program. If non-NIL, treat failure to start the same as failure from the program itself, by setting the status and exit-code fields. Default is ccl::*silently-ignore-catastrophic-failure-in-run-program*.

Runs the specified program in an external (Unix) process, returning an object of type EXTERNAL-PROCESS if successful.

The implementation involves a lisp process/thread which monitors the status of this external process and arranges for the standard I/O descriptors for the external process to be connected to the specified lisp streams. Since this may require the monitoring thread to do I/O on lisp streams in some cases, streams provided as the values of the :INPUT, :OUTPUT, and :ERROR arguments should not be private to some other lisp thread.

Sends signal number sig to the external process proc (which would have been returned by run-program. Typically, it would only be useful to call this function if the proc was created with :wait nil.

If successful, the function returns t; otherwise, an error is signaled.

However, if error-if-exited is nil, and the attempt to signal the external process fails because the external process has already exited, the function will return nil rather than signaling an error.

Returns the operating system process ID assigned to the external-process object proc.

Returns the lisp stream which is used to write input to the external-process object proc, if it has one. This will be the stream created when the :input argument to run-program is specified as :stream.

Returns the lisp stream which is used to read output from the external-process object proc, if there is one. This is the stream created when the :output argument to run-program is specified as :stream.

Returns the stream which is used to read error output from a given OS subprocess, if there is one. This is the stream created when the :error argument to run-program is specified as :stream.

Returns, as multiple values, a keyword denoting the status of the external process proc (one of :running, :stopped, signaled, or exited), and the exit code or terminating signal if the first value is other than :running.

class-name

a string which denotes an existing class name, or a symbol which can be mapped to such a string via the standard name-mapping conventions for class names

Used to refer to a known ObjC class by name. (Via the use LOAD-TIME-VALUE, the results of a class-name -> class lookup are cached.)

objc:@class is obsolete as of late 2004, because find-class now works on ObjC classes. It is described here only because some old code still uses it.

string

a string constant, used to canonically refer to an ObjC method selector

Used to refer to an ObjC method selector (method name). Uses LOAD-TIME-VALUE to cache the result of a string -> selector lookup.

name-and-result-type

either an Objective-C message name, for methods that return a value of type :ID, or a list containing an Objective-C message name and a foreign type specifier for methods with a different foreign result type.

receiver-arg-and-class

a two-element list whose first element is a variable name and whose second element is the Lisp name of an Objective-C class or metaclass. The receiver variable name can be any bindable lisp variable name, but SELF might be a reasonable choice. The receiver variable is declared to be "unsettable"; i.e., it is an error to try to change the value of the receiver in the body of the method definition.

other-args

either variable names (denoting parameters of type :ID) or 2-element lists whose first element is a variable name and whose second element is a foreign type specifier.

Defines an Objective-C-callable method which implements the specified message selector for instances of the existing named Objective-C class.

For a detailed description of the features and restrictions of the OBJC:DEFMETHOD macro, see the section Using objc:defmethod.

selector

either a string which represents the name of the selector or a list which describes the method's return type, selector components, and argument types (see below.) If the first form is used, then the first form in the body must be a list which describes the selector's argument types and return value type, as per DEFCALLBACK.

class-name

either a string which names an existing ObjC class name or a list symbol which can map to such a string via the standard name-mapping conventions for class names. (Note that the "canonical" lisp class name is such a symbol)

Defines an ObjC-callable method which implements the specified message selector for instances of the existing ObjC class class-name.

As per DEFINE-OBJC-METHOD

Like DEFINE-OBJC-METHOD, only used to define methods on the class named by class-name and on its subclasses.

For both DEFINE-OBJC-METHOD and DEFINE-OBJC-CLASS-METHOD, the "selector" argument can be a list whose first element is a foreign type specifier for the method's return value type and whose subsequent elements are either:

• a non-keyword symbol, which can be mapped to a selector string for a parameterless method according to the standard name-mapping conventions for method selectors.

• a list of alternating keywords and variable/type specifiers, where the set of keywords can be mapped to a selector string for a parameterized method according to the standard name-mapping conventions for method selectors and each variable/type-specifier is either a variable name (denoting a value of type :ID) or a list whose CAR is a variable name and whose CADR is the corresponding argument's foreign type specifier.

This variable is currently only used by the standard reader macro function for #\; (single-line comments); that function reads successive characters until EOF, a #\NewLine is read, or a character EQL to the value of *alternate-line-terminator* is read. In Clozure CL for Darwin, the value of this variable is initially #\Return ; in Clozure CL for other OSes, it's initially NIL.

Their default treatment by the #\; reader macro is the primary way in which #\Return and #\Linefeed differ syntactically; by extending the #\; reader macro to (conditionally) treat #\Return as a comment-terminator, that distinction is eliminated. This seems to make LOAD and COMPILE-FILE insensitive to line-termination issues in many cases. It could fail in the (hopefully rare) case where a LF-terminated (Unix) text file contains embedded #\Return characters, and this mechanism isn't adequate to handle cases where newlines are embedded in string constants or other tokens (and presumably should be translated from an external convention to the external one) : it doesn't change what READ-CHAR or READ-LINE "see", and that may be necessary to handle some more complicated cases.

NS:NS-STRING

:string

a Lisp string which is to be the content of the newly-created ns-lisp-string.

This class implements the interface of an NSString, which means that it can be passed to any Cocoa or Core Foundation function which expects one.

The string itself is stored on the Lisp heap, which means that its memory management is automatic. However, the ns-lisp-string object itself is a foreign object (that is, it has an objc metaclass), and resides on the foreign heap. Therefore, it is necessary to explicitly free it, by sending a dealloc message.

You can create an ns-lisp-string with make-instance, just like any normal Lisp class:

? (defvar *the-string*
     (make-instance 'ccl::ns-lisp-string
                    :string "Hello, Cocoa."))

When you are done with the string, you must explicitly deallocate it:

? (ccl::send *the-string* 'dealloc)

You may wish to use an unwind-protect form to ensure that this happens:

(let (*the-string*)
  (unwind-protect (progn (setq *the-string*
                               (make-instance 'ccl::ns-lisp-string
                                              :string "Hello, Cocoa."))
                         (format t "~&The string is ~D characters long.~%"
                                 (ccl::send *the-string* 'length)))
    (when *the-string*
      (ccl::send *the-string* 'dealloc))))

Currently, ns-lisp-string is defined in the file ccl/examples/cocoa-backtrace.lisp, which is a rather awkward place. It was probably not originally meant as a public utility at all. It would be good if it were moved someplace else. Use at your own risk.

type

The type of population, one of :LIST (the default) or :ALIST

initial-contents

A sequence of elements (or conses, for :alist) to be used to initialize the population. The sequence itself (and the conses in case of an alist) is not stored in the population, a new list or alist is created to hold the elements.

Creates a new population of the specified type.

returns the type of population, one of :LIST or :ALIST

returns the list encapsulated in population. Note that as long as there is a direct (non-weak) reference to this list, it will not be modified by the garbage collector. Therefore it is safe to traverse the list, and even modify it, no different from any other list. If you want the elements to become garbage-collectable again, you must stop referring to the list directly.

Sets the list encapsulated in population to contents. Contents is not copied, it is used directly.

Allocates and returns a cons cell that does not move on garbage collection and thus does not trigger re-hashing when used as a key in a hash table. Usage is equivalent to regular cons.

Returns the number of static conses that have been reserved since the lisp was created. This number will be a multiple of 32768. The memory for static conses is, in many respects, part of the dynamic heap. It is physically adjacent to it (immediately precedes the dynamic heap area in memory), and its contents are subject to full GC (but not compaction).

Returns the length of the static cons freelist. In other words, this is number of static conses available for use before space for another 32768 static cons cells is reserved.

Causes a full GC to occur as soon as possible. Returns NIL.

Returns the value of the kernel variable that specifies the amount of free space to leave in the heap after full GC.

new-threshold

The requested new lisp-heap-gc-threshold.

Sets the value of the kernel variable that specifies the amount of free space to leave in the heap after full GC to new-value, which should be a non-negative fixnum. Returns the value of that kernel variable (which may be somewhat larger than what was specified).

Tries to grow or shrink lisp's heap space, so that the free space is (approximately) equal to the current heap threshold. Returns NIL

arg

a generalized boolean

Enables the EGC if arg is non-nil, disables the EGC otherwise. Returns the previous enabled status. Although this function is thread-safe (in the sense that calls to it are serialized), it doesn't make a whole lot of sense to be turning the EGC on and off from multiple threads ...

Returns T if the EGC was enabled at the time of the call, NIL otherwise.

Returns T if the EGC was active at the time of the call, NIL otherwise. Since this is generally a volatile piece of information, it's not clear whether this function serves a useful purpose when native threads are involved.

Returns, as multiple values, the sizes in kilobytes of the thresholds associated with the youngest ephemeral generation, the middle ephemeral generation, and the oldest ephemeral generation

generation-0-size

the requested threshold size of the youngest generation, in kilobytes

generation-1-size

the requested threshold size of the middle generation, in kilobytes

generation-2-size

the requested threshold size of the oldest generation, in kilobytes

Puts the indicated threshold sizes in effect. Each threshold indicates the total size that may be allocated in that and all younger generations before a GC is triggered. Disables EGC while setting the values. (The provided threshold sizes are rounded up to a multiple of 64Kbytes in Clozure CL 0.14 and to a multiple of 32KBytes in earlier versions.)

arg

a generalized boolean

Tries to influence the GC to retain/recycle the pages allocated between GCs if arg is true, and to release them otherwise. This is generally a tradeoff between paging and other VM considerations.

Returns T if the GC tries to retain pages between full GCs and NIL if it's trying to release them to improve VM paging performance.