Changeset 8673


Ignore:
Timestamp:
Mar 6, 2008, 8:54:02 PM (12 years ago)
Author:
mikel
Message:

added documentation of stack sizes, with-encoded-cstrs. added a section documenting the IDE.

Location:
trunk/source/doc/src
Files:
1 added
4 edited

Legend:

Unmodified
Added
Removed
  • trunk/source/doc/src/ccl-documentation.xml

    r8664 r8673  
    2222<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
    2323            href="using.xml"/>
     24<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
     25            href="ide.xml"/>
    2426<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
    2527            href="q-and-a.xml"/>
  • trunk/source/doc/src/ffi.xml

    r8663 r8673  
    11531153          </variablelist>
    11541154        </sect3>
     1155
     1156<sect3>
     1157  <title>with-encoded-cstrs [Macro]</title>
     1158
     1159  <variablelist>
     1160        <varlistentry>
     1161          <term>Syntax</term>
     1162
     1163          <listitem>
     1164                <para>with-encoded-cstrs ENCODING-NAME (varI stringI)* &#38;body body</para>
     1165          </listitem>
     1166        </varlistentry>
     1167
     1168        <varlistentry>
     1169          <term>Description</term>
     1170
     1171          <listitem>
     1172                <para>Executes body in an environment in which each varI is
     1173                  bound to a macptr which encapsulates the %address of a
     1174                  stack-allocated region of into which each stringI (and a
     1175                  trailing NUL character) has been copied. Returns whatever
     1176                  value(s) body returns.</para>
     1177
     1178        <para>ENCODING-NAME is a keyword constant that names a
     1179          character encoding. Each foreign string is encoded in the
     1180          named encoding. Each foreign string has dynamic
     1181          extent.</para>
     1182
     1183        <para>WITH-ENCODED-CSTRS does not automatically prepend
     1184        bte-order marks to its output; the size of the terminating
     1185        #\NUL character depends on the number of octets per code unit
     1186        in the encoding.</para>
     1187
     1188        <para>The expression</para>
     1189
     1190        <programlisting>(ccl:with-cstrs ((x "x")) (#_puts x))</programlisting>
     1191
     1192        <para>is functionally equivalent to</para>
     1193
     1194        <programlisting>(ccl:with-encoded-cstrs :iso-8859-1 ((x "x")) (#_puts x))</programlisting>
     1195          </listitem>
     1196        </varlistentry>
     1197
     1198        <varlistentry>
     1199          <term>Arguments</term>
     1200
     1201          <listitem>
     1202                <para>&#x00A0;</para>
     1203
     1204                <variablelist>
     1205                  <varlistentry>
     1206                    <term>varI</term>
     1207
     1208                    <listitem>
     1209                      <para>A symbol (variable name)</para>
     1210                    </listitem>
     1211                  </varlistentry>
     1212
     1213                  <varlistentry>
     1214                    <term>stringI</term>
     1215
     1216                    <listitem>
     1217                      <para>An expression which should evaluate to a lisp string</para>
     1218                    </listitem>
     1219                  </varlistentry>
     1220                </variablelist>
     1221          </listitem>
     1222        </varlistentry>
     1223  </variablelist>
     1224</sect3>
    11551225
    11561226        <sect3>
  • trunk/source/doc/src/threads.xml

    r8659 r8673  
    165165    </sect1>
    166166
    167     <sect1 id="Implementation-Decisions-and-Open-Questions">
    168       <title>Implementation Decisions and Open Questions</title>
    169       <para> As of August 2003:</para>
    170       <itemizedlist>
    171         <listitem>
    172           <para>It's not clear that exposing
    173           PROCESS-SUSPEND/PROCESS-RESUME is a good idea: it's not clear
    174           that they offer ways to win, and it's clear that they offer
    175           ways to lose.</para>
    176         </listitem>
    177         <listitem>
    178           <para>It has traditionally been possible to reset and enable
    179           a process that's "exhausted" . (As used here, the
    180           term"exhausted" means that the process's initial function
    181           hasrun and returned and the underlying native thread has
    182           beendeallocated.) One of the principle uses of PROCESS-RESET
    183           is to "recycle" threads; enabling an exhausted process
    184           involves creating a new native thread (and stacks and
    185           synchronization objects and ...),and this is the sort of
    186           overhead that such a recycling scheme is seeking to avoid. It
    187           might be worth trying to tighten things up and declare that
    188           it's an error to apply PROCESS-ENABLE to an exhausted thread
    189           (and to make PROCESS-ENABLE detect this error.)</para>
    190         </listitem>
    191         <listitem>
    192           <para>When native threads that aren't created by &CCL;
    193           first call into lisp, a "foreign process" is created, and
    194           that process is given its own set of initial bindings and set
    195           up to look mostly like a process that had been created by
    196           MAKE-PROCESS. The life cycle of a foreign process is
    197           certainly different from that of a lisp-created one: it
    198           doesn't make sense to reset/preset/enable a foreign process,
    199           and attempts to perform these operations should be
    200           detectedand treated as errors.</para>
    201         </listitem>
    202       </itemizedlist>
    203     </sect1>
     167
     168<sect1 id="Implementation-Decisions-and-Open-Questions">
     169  <title>Implementation Decisions and Open Questions</title>
     170  <sect2>
     171    <title>Thread Stack Sizes</title>
     172    <para>When you use MAKE-PROCESS to create a thread, you can
     173      specify a stack size. &CCL; does not impose a limit on the stack
     174      size you choose, but there is some evidence that choosing a
     175      stack size larger than the operating system's limit can cause
     176      excessive paging activity, at least on some operating
     177      systems.</para>
     178    <para>The maximum stack size is operating-system-dependent. You
     179      can use shell commands to determine what it is on your
     180      platform. In bash, use "ulimit -s -H" to find the limit; in
     181      tcsh, use "limit -h s".</para>
     182    <para>This issue does not affect programs that create threads
     183      using the default stack size, which you can do either by
     184      specifying no value for the :stack-size argument to
     185      MAKE-PROCESS, or by specifying the value
     186      CCL::*default-control-stack-size*.</para>
     187    <para>If your program creates threads with a specified stack size,
     188    and that size is larger than the OS-specified limit, you may want
     189    to consider reducing the stack size in order to avoid possible
     190    excessive paging activity.</para>
     191  </sect2>
     192  <sect2>
     193    <title> As of August 2003:</title>
     194    <itemizedlist>
     195      <listitem>
     196            <para>It's not clear that exposing
     197              PROCESS-SUSPEND/PROCESS-RESUME is a good idea: it's not clear
     198              that they offer ways to win, and it's clear that they offer
     199              ways to lose.</para>
     200          </listitem>
     201      <listitem>
     202            <para>It has traditionally been possible to reset and enable
     203              a process that's "exhausted" . (As used here, the
     204              term"exhausted" means that the process's initial function
     205              hasrun and returned and the underlying native thread has
     206              beendeallocated.) One of the principle uses of PROCESS-RESET
     207              is to "recycle" threads; enabling an exhausted process
     208              involves creating a new native thread (and stacks and
     209              synchronization objects and ...),and this is the sort of
     210              overhead that such a recycling scheme is seeking to avoid. It
     211              might be worth trying to tighten things up and declare that
     212              it's an error to apply PROCESS-ENABLE to an exhausted thread
     213              (and to make PROCESS-ENABLE detect this error.)</para>
     214          </listitem>
     215      <listitem>
     216            <para>When native threads that aren't created by &CCL;
     217              first call into lisp, a "foreign process" is created, and
     218              that process is given its own set of initial bindings and set
     219              up to look mostly like a process that had been created by
     220              MAKE-PROCESS. The life cycle of a foreign process is
     221              certainly different from that of a lisp-created one: it
     222              doesn't make sense to reset/preset/enable a foreign process,
     223              and attempts to perform these operations should be
     224              detectedand treated as errors.</para>
     225          </listitem>
     226    </itemizedlist>
     227  </sect2>
     228</sect1>
     229
     230
    204231
    205232    <sect1 id="Porting-Code-from-the-Old-Thread-Model">
  • trunk/source/doc/src/using.xml

    r8669 r8673  
    151151  </sect1>
    152152
     153  <sect1 id="Strings-and-Pathanmes"><title>Strings and Pathnames</title>
     154    <sect2>
     155      <title>OS X (Darwin)</title>
     156
     157      <para>Clozure CL assumes that pathname strings are decomposed UTF-8.</para>
     158    </sect2>
     159    <sect2>
     160      <title>Linux</title>
     161
     162      <para>Pathname strings are treated as null-terminated strings
     163        encoded according to the current locale.</para>
     164    </sect2>
     165    <sect2>
     166      <title>FreeBSD</title>
     167
     168      <para>Pathname strings are treated as null-terminated strings
     169        encoded according to the current locale; a future release may
     170        change this convention to use UTF-8.</para>
     171    </sect2>
     172  </sect1>
    153173</chapter>
Note: See TracChangeset for help on using the changeset viewer.