mirror of
https://gitlab.com/embeddable-common-lisp/ecl.git
synced 2026-01-12 12:21:15 -08:00
365 lines
No EOL
11 KiB
XML
365 lines
No EOL
11 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!DOCTYPE book [
|
|
<!ENTITY % eclent SYSTEM "ecl.ent">
|
|
%eclent;
|
|
]>
|
|
<book xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
|
|
<chapter>
|
|
<title>Memory Management</title>
|
|
<section xml:id="ext.memory.dict">
|
|
<title>Memory Management Reference</title>
|
|
|
|
<!-- ====================================================================== -->
|
|
<!-- EXT:STACK-OVERFLOW -->
|
|
<!-- ====================================================================== -->
|
|
|
|
<refentry xml:id="ref.memory.stack-overflow">
|
|
<refnamediv>
|
|
<refname><classname>ext:stack-overflow</classname></refname>
|
|
<refpurpose>Stack overflow condition.</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<title>Class Precedence List</title>
|
|
<para>
|
|
<classname>ext:stack-overflow</classname>,
|
|
<classname>storage-condition</classname>,
|
|
<classname>serious-condition</classname>,
|
|
<classname>condition</classname>,
|
|
<classname>t</classname>
|
|
</para>
|
|
</refsynopsisdiv>
|
|
|
|
<refsynopsisdiv>
|
|
<title>Methods</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>ext:stack-overflow-size</funcdef>
|
|
<paramdef><parameter>condition</parameter></paramdef>
|
|
<modifier><replaceable>integer</replaceable></modifier>
|
|
</funcprototype>
|
|
<funcprototype>
|
|
<funcdef>ext:stack-overflow-type</funcdef>
|
|
<paramdef><parameter>condition</parameter></paramdef>
|
|
<modifier><replaceable>concept</replaceable></modifier>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><replaceable>integer</replaceable></term>
|
|
<listitem><para>A non-negative integer.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><replaceable>concept</replaceable></term>
|
|
<listitem><para>A symbol from <xref
|
|
linkend="table.memory.limits"/>, except
|
|
<varname>ext:heap-size</varname>.</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<para>This condition is signaled when one of the stack limits in
|
|
<xref linkend="table.memory.limits"/> are violated or dangerously
|
|
approached. It can be handled by resetting the limits and
|
|
continuing, or jumping to an outer control point.</para>
|
|
</refsect1>
|
|
|
|
</refentry>
|
|
|
|
<!-- ====================================================================== -->
|
|
<!-- EXT:STORAGE-EXHAUSTED -->
|
|
<!-- ====================================================================== -->
|
|
|
|
<refentry xml:id="ref.memory.storage-exhausted">
|
|
<refnamediv>
|
|
<refname><classname>ext:storage-exhausted</classname></refname>
|
|
<refpurpose>Memory overflow condition.</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<title>Class Precedence List</title>
|
|
<para>
|
|
<classname>ext:storage-exhausted</classname>,
|
|
<classname>storage-condition</classname>,
|
|
<classname>serious-condition</classname>,
|
|
<classname>condition</classname>,
|
|
<classname>t</classname>
|
|
</para>
|
|
</refsynopsisdiv>
|
|
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<para>This condition is signaled when &ECL; exhausts the
|
|
<varname>ext:heap-size</varname> limit from <xref
|
|
linkend="table.memory.limits"/>. In handling this condition &ECL; follows
|
|
this logic</para>
|
|
<itemizedlist>
|
|
<listitem><para>If the heap size limit was set to 0 (that is no limit), but
|
|
there is some free space in the safety region &ECL; frees this space and
|
|
issues a non-restartable error. The user may jump to an outer point or
|
|
quit.</para></listitem>
|
|
|
|
<listitem><para>If the heap size had a finite limit, &ECL; offers the user
|
|
the chance to resize it, issuing a restartable condition. The user may at
|
|
this point use <code>(ext:set-limit 'ext:heap-size 0)</code> to remove the
|
|
heap limit and avoid further messages, or use the <code>(continue)</code>
|
|
restart to let &ECL; enlarge the heap by some amount.</para></listitem>
|
|
|
|
<listitem><para>Independently of the heap size limit, if &ECL; finds that
|
|
ther is no space to free or to grow, &ECL; simply quits. There will be no
|
|
chance to do some cleanup because there is no way to cons any additional
|
|
data.</para></listitem>
|
|
</itemizedlist>
|
|
</refsect1>
|
|
|
|
</refentry>
|
|
|
|
<!-- ====================================================================== -->
|
|
<!-- EXT:GET-FINALIZER -->
|
|
<!-- ====================================================================== -->
|
|
|
|
<refentry xml:id="ref.memory.get-finalizer">
|
|
<refnamediv>
|
|
<refname><function>ext:get-finalizer</function></refname>
|
|
<refpurpose>Return finalizer associated to an object.</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<title>Function</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>ext:get-finalizer</funcdef>
|
|
<paramdef><parameter>object</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><replaceable>object</replaceable></term>
|
|
<listitem><para>Any lisp object.</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<para>This function returns the finalizer associated to an object, or &nil;.</para>
|
|
</refsect1>
|
|
|
|
</refentry>
|
|
|
|
<!-- ====================================================================== -->
|
|
<!-- EXT::GET-LIMIT -->
|
|
<!-- ====================================================================== -->
|
|
|
|
<refentry xml:id="ref.memory.get-limit">
|
|
<refnamediv>
|
|
<refname><function>ext:get-limit</function></refname>
|
|
<refpurpose>Query a memory or stack limit.</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<title>Function</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>ext:get-limit</funcdef>
|
|
<paramdef><parameter>concept</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><replaceable>concept</replaceable></term>
|
|
<listitem><para>A symbol.</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>Queries the different memory and stack limits that condition
|
|
&ECL;'s behavior. The value to be queried is denoted by the symbol
|
|
<replaceable>concept</replaceable>, which should be one from the
|
|
list <xref linkend="table.memory.limits"/></para>
|
|
|
|
</refsect1>
|
|
|
|
</refentry>
|
|
|
|
<!-- ====================================================================== -->
|
|
<!-- EXT::SET-FINALIZER -->
|
|
<!-- ====================================================================== -->
|
|
|
|
<refentry xml:id="ref.memory.set-finalizer">
|
|
<refnamediv>
|
|
<refname><function>ext:set-finalizer</function></refname>
|
|
<refpurpose>Associate a finalizer to an object.</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<title>Function</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>ext:set-finalizer</funcdef>
|
|
<paramdef><parameter>object</parameter></paramdef>
|
|
<paramdef><parameter>function</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><replaceable>object</replaceable></term>
|
|
<listitem><para>Any lisp object.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><replaceable>function</replaceable></term>
|
|
<listitem><para>A function or closure that takes one argument or &nil;.</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>If <replaceable>function</replaceable> is &nil; no finalizer is
|
|
associated to the object. Otherwise <replaceable>function</replaceable> must
|
|
be a function or a closure of one argument, which will be invoked before the
|
|
object is destroyed.</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Example</title>
|
|
<para>Close a file associated to an object.</para>
|
|
<programlisting>
|
|
(defclass my-class () ((file :initarg :file :initform nil)))
|
|
|
|
(defun finalize-my-class (x)
|
|
(let ((s (slot-value x 'file)))
|
|
(when s (format t "~%;;; Closing" s) (close s))))
|
|
|
|
(defmethod initialize-instance :around ((my-instance my-class) &rest args)
|
|
(ext:set-finalizer my-instance #'finalize-my-class)
|
|
(call-next-method))
|
|
|
|
(progn
|
|
(make-instance 'my-class :file (open "~/.ecl.old" :direction :input))
|
|
nil)
|
|
|
|
(si::gc t)
|
|
(si::gc t)
|
|
|
|
;; Closing
|
|
</programlisting>
|
|
</refsect1>
|
|
|
|
</refentry>
|
|
|
|
<!-- ====================================================================== -->
|
|
<!-- EXT::SET-LIMIT -->
|
|
<!-- ====================================================================== -->
|
|
|
|
<refentry xml:id="ref.memory.set-limit">
|
|
<refnamediv>
|
|
<refname><function>ext:set-limit</function></refname>
|
|
<refpurpose>Set a memory or stack limit.</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<title>Function</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>ext:set-limit</funcdef>
|
|
<paramdef><parameter>concept</parameter></paramdef>
|
|
<paramdef><parameter>value</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><replaceable>concept</replaceable></term>
|
|
<listitem><para>A symbol.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><replaceable>function</replaceable></term>
|
|
<listitem><para>A positive integer.</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>Changes the different memory and stack limits that condition
|
|
&ECL;'s behavior. The value to be changed is denoted by the symbol
|
|
<replaceable>concept</replaceable>, while the
|
|
<replaceable>value</replaceable> is the new maximum size. The valid
|
|
symbols and units are listed in <xref
|
|
linkend="table.memory.limits"/>.</para>
|
|
|
|
<para>Note that the limit has to be positive, but it may be smaller
|
|
than the previous value of the limit. However, if the supplied value
|
|
is smaller than what &ECL; is using at the moment, the new value
|
|
will be silently ignored.</para>
|
|
|
|
<table xml:id="table.memory.limits">
|
|
<title>Customizable memory limits</title>
|
|
<tgroup cols="3">
|
|
<thead>
|
|
<row>
|
|
<entry>Concept</entry>
|
|
<entry>Units</entry>
|
|
<entry>Default</entry>
|
|
<entry>Command line</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry><varname>ext:frame-stack</varname></entry>
|
|
<entry>Nested frames</entry>
|
|
<entry>2048</entry>
|
|
<entry>--frame-stack</entry>
|
|
</row>
|
|
<row>
|
|
<entry><varname>ext:binding-stack</varname></entry>
|
|
<entry>Bindings</entry>
|
|
<entry>8192</entry>
|
|
<entry></entry>
|
|
</row>
|
|
<row>
|
|
<entry><varname>ext:c-stack</varname></entry>
|
|
<entry>Bytes</entry>
|
|
<entry>128 kilobytes</entry>
|
|
<entry>--c-stack</entry>
|
|
</row>
|
|
<row>
|
|
<entry><varname>ext:heap-size</varname></entry>
|
|
<entry>Bytes</entry>
|
|
<entry>256 megabytes</entry>
|
|
<entry>--heap-size</entry>
|
|
</row>
|
|
<row>
|
|
<entry><varname>ext:lisp-stack</varname></entry>
|
|
<entry>Bytes</entry>
|
|
<entry>32 kilobytes</entry>
|
|
<entry>--lisp-stack</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
|
|
</refsect1>
|
|
|
|
</refentry>
|
|
</section>
|
|
</chapter>
|
|
</book>
|
|
<!-- Keep this comment at the end of the file
|
|
Local variables:
|
|
mode: nxml
|
|
sgml-parent-document: "ecl.xml"
|
|
sgml-indent-step: 1
|
|
nxml-child-indent: 1
|
|
nxml-outline-child-indent: 1
|
|
fill-column: 79
|
|
End:
|
|
--> |