/usr/share/doc/racket/inside/overview.html is in racket-doc 6.1-4.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html><head><meta http-equiv="content-type" content="text/html; charset=utf-8"/><title>1 Overview</title><link rel="stylesheet" type="text/css" href="../scribble.css" title="default"/><link rel="stylesheet" type="text/css" href="../racket.css" title="default"/><link rel="stylesheet" type="text/css" href="../manual-style.css" title="default"/><link rel="stylesheet" type="text/css" href="../manual-racket.css" title="default"/><link rel="stylesheet" type="text/css" href="../doc-site.css" title="default"/><script type="text/javascript" src="../scribble-common.js"></script><script type="text/javascript" src="../manual-racket.js"></script><script type="text/javascript" src="../doc-site.js"></script><script type="text/javascript" src="../local-redirect/local-redirect.js"></script><script type="text/javascript" src="../local-redirect/local-user-redirect.js"></script><!--[if IE 6]><style type="text/css">.SIEHidden { overflow: hidden; }</style><![endif]--></head><body id="doc-racket-lang-org"><div class="tocset"><div class="tocview"><div class="tocviewlist tocviewlisttopspace"><div class="tocviewtitle"><table cellspacing="0" cellpadding="0"><tr><td style="width: 1em;"><a href="javascript:void(0);" title="Expand/Collapse" class="tocviewtoggle" onclick="TocviewToggle(this,"tocview_0");">▼</a></td><td></td><td><a href="index.html" class="tocviewlink" data-pltdoc="x">Inside:<span class="mywbr"> </span> Racket C API</a></td></tr></table></div><div class="tocviewsublisttop" style="display: block;" id="tocview_0"><table cellspacing="0" cellpadding="0"><tr><td align="right">1 </td><td><a href="" class="tocviewselflink" data-pltdoc="x">Overview</a></td></tr><tr><td align="right">2 </td><td><a href="embedding.html" class="tocviewlink" data-pltdoc="x">Embedding into a Program</a></td></tr><tr><td align="right">3 </td><td><a href="Writing_Racket_Extensions.html" class="tocviewlink" data-pltdoc="x">Writing Racket Extensions</a></td></tr><tr><td align="right">4 </td><td><a href="im_values_types.html" class="tocviewlink" data-pltdoc="x">Values and Types</a></td></tr><tr><td align="right">5 </td><td><a href="im_memoryalloc.html" class="tocviewlink" data-pltdoc="x">Memory Allocation</a></td></tr><tr><td align="right">6 </td><td><a href="im_env.html" class="tocviewlink" data-pltdoc="x">Namespaces and Modules</a></td></tr><tr><td align="right">7 </td><td><a href="Procedures.html" class="tocviewlink" data-pltdoc="x">Procedures</a></td></tr><tr><td align="right">8 </td><td><a href="Evaluation.html" class="tocviewlink" data-pltdoc="x">Evaluation</a></td></tr><tr><td align="right">9 </td><td><a href="exceptions.html" class="tocviewlink" data-pltdoc="x">Exceptions and Escape Continuations</a></td></tr><tr><td align="right">10 </td><td><a href="threads.html" class="tocviewlink" data-pltdoc="x">Threads</a></td></tr><tr><td align="right">11 </td><td><a href="config.html" class="tocviewlink" data-pltdoc="x">Parameterizations</a></td></tr><tr><td align="right">12 </td><td><a href="contmarks.html" class="tocviewlink" data-pltdoc="x">Continuation Marks</a></td></tr><tr><td align="right">13 </td><td><a href="im_encodings.html" class="tocviewlink" data-pltdoc="x">String Encodings</a></td></tr><tr><td align="right">14 </td><td><a href="Bignums__Rationals__and_Complex_Numbers.html" class="tocviewlink" data-pltdoc="x">Bignums, Rationals, and Complex Numbers</a></td></tr><tr><td align="right">15 </td><td><a href="Ports_and_the_Filesystem.html" class="tocviewlink" data-pltdoc="x">Ports and the Filesystem</a></td></tr><tr><td align="right">16 </td><td><a href="Structures.html" class="tocviewlink" data-pltdoc="x">Structures</a></td></tr><tr><td align="right">17 </td><td><a href="security.html" class="tocviewlink" data-pltdoc="x">Security Guards</a></td></tr><tr><td align="right">18 </td><td><a href="Custodians.html" class="tocviewlink" data-pltdoc="x">Custodians</a></td></tr><tr><td align="right">19 </td><td><a href="Subprocesses.html" class="tocviewlink" data-pltdoc="x">Subprocesses</a></td></tr><tr><td align="right">20 </td><td><a href="Miscellaneous_Utilities.html" class="tocviewlink" data-pltdoc="x">Miscellaneous Utilities</a></td></tr><tr><td align="right"></td><td><a href="doc-index.html" class="tocviewlink" data-pltdoc="x">Index</a></td></tr></table></div></div><div class="tocviewlist"><table cellspacing="0" cellpadding="0"><tr><td style="width: 1em;"><a href="javascript:void(0);" title="Expand/Collapse" class="tocviewtoggle" onclick="TocviewToggle(this,"tocview_1");">►</a></td><td>1 </td><td><a href="" class="tocviewselflink" data-pltdoc="x">Overview</a></td></tr></table><div class="tocviewsublistbottom" style="display: none;" id="tocview_1"><table cellspacing="0" cellpadding="0"><tr><td align="right">1.1 </td><td><a href="#%28part.__.Scheme__versus__.Racket_%29" class="tocviewlink" data-pltdoc="x">“Scheme” versus “Racket”</a></td></tr><tr><td align="right">1.2 </td><td><a href="#%28part._.Building_.Racket_from_.Source%29" class="tocviewlink" data-pltdoc="x">Building Racket from Source</a></td></tr><tr><td align="right">1.3 </td><td><a href="#%28part._.C.G.C._versus._3m%29" class="tocviewlink" data-pltdoc="x">CGC versus 3m</a></td></tr><tr><td align="right">1.4 </td><td><a href="#%28part._embedding-and-extending%29" class="tocviewlink" data-pltdoc="x">Embedding and Extending Racket</a></td></tr><tr><td align="right">1.5 </td><td><a href="#%28part._places%29" class="tocviewlink" data-pltdoc="x">Racket and Places</a></td></tr><tr><td align="right">1.6 </td><td><a href="#%28part._.Racket_and_.Threads%29" class="tocviewlink" data-pltdoc="x">Racket and Threads</a></td></tr><tr><td align="right">1.7 </td><td><a href="#%28part._im~3aunicode%29" class="tocviewlink" data-pltdoc="x">Racket, Unicode, Characters, and Strings</a></td></tr><tr><td align="right">1.8 </td><td><a href="#%28part._im~3aintsize%29" class="tocviewlink" data-pltdoc="x">Integers</a></td></tr></table></div></div></div><div class="tocsub"><div class="tocsubtitle">On this page:</div><table class="tocsublist" cellspacing="0"><tr><td><span class="tocsublinknumber">1.1<tt> </tt></span><a href="#%28part.__.Scheme__versus__.Racket_%29" class="tocsubseclink" data-pltdoc="x">“Scheme” versus “Racket”</a></td></tr><tr><td><span class="tocsublinknumber">1.2<tt> </tt></span><a href="#%28part._.Building_.Racket_from_.Source%29" class="tocsubseclink" data-pltdoc="x">Building Racket from Source</a></td></tr><tr><td><span class="tocsublinknumber">1.3<tt> </tt></span><a href="#%28part._.C.G.C._versus._3m%29" class="tocsubseclink" data-pltdoc="x">CGC versus 3m</a></td></tr><tr><td><span class="tocsublinknumber">1.4<tt> </tt></span><a href="#%28part._embedding-and-extending%29" class="tocsubseclink" data-pltdoc="x">Embedding and Extending Racket</a></td></tr><tr><td><span class="tocsublinknumber">1.5<tt> </tt></span><a href="#%28part._places%29" class="tocsubseclink" data-pltdoc="x">Racket and Places</a></td></tr><tr><td><span class="tocsublinknumber">1.6<tt> </tt></span><a href="#%28part._.Racket_and_.Threads%29" class="tocsubseclink" data-pltdoc="x">Racket and Threads</a></td></tr><tr><td><span class="tocsublinknumber">1.7<tt> </tt></span><a href="#%28part._im~3aunicode%29" class="tocsubseclink" data-pltdoc="x">Racket, Unicode, Characters, and Strings</a></td></tr><tr><td><span class="tocsublinknumber">1.8<tt> </tt></span><a href="#%28part._im~3aintsize%29" class="tocsubseclink" data-pltdoc="x">Integers</a></td></tr></table></div></div><div class="maincolumn"><div class="main"><div class="navsettop"><span class="navleft"><form class="searchform"><input class="searchbox" style="color: #888;" type="text" value="...search manuals..." title="Enter a search string to search the manuals" onkeypress="return DoSearchKey(event, this, "6.1", "../");" onfocus="this.style.color="black"; this.style.textAlign="left"; if (this.value == "...search manuals...") this.value="";" onblur="if (this.value.match(/^ *$/)) { this.style.color="#888"; this.style.textAlign="center"; this.value="...search manuals..."; }"/></form> <a href="../index.html" title="up to the documentation top" data-pltdoc="x" onclick="return GotoPLTRoot("6.1");">top</a></span><span class="navright"> <a href="index.html" title="backward to "Inside: Racket C API"" data-pltdoc="x">← prev</a> <a href="index.html" title="up to "Inside: Racket C API"" data-pltdoc="x">up</a> <a href="embedding.html" title="forward to "2 Embedding into a Program"" data-pltdoc="x">next →</a></span> </div><h3 x-source-module="(lib "scribblings/inside/inside.scrbl")" x-part-tag=""overview"">1<tt> </tt><a name="(part._overview)"></a>Overview</h3><p>The Racket run-time system is responsible for the implementation
primitive datatypes such as numbers and strings, the evaluation and/or
JIT compilation of Racket bytecode, the macro expansion and
compilation of Racket from source to bytecode, the allocation and
reclamation of memory used during evaluation, and the scheduling
concurrent threads and parallel tasks.</p><p>Much of the language provided by <a href="http://download.racket-lang.org/docs/6.1/html/local-redirect/index.html?doc=reference&rel=index.html&version=6.1" class="RktModLink Sq" data-pltdoc="x"><span class="RktSym">racket/base</span></a> is
implemented in a more primitive dialect of Racket that is provided by
the run-time system. Future versions of Racket are likely to move
macro expansion, compilation, and many “primitive” functions into
such Racket-implemented libraries, instead of having them built into
the run-time system.</p><h4 x-source-module="(lib "scribblings/inside/inside.scrbl")" x-part-tag=""_Scheme__versus__Racket_"">1.1<tt> </tt><a name="(part.__.Scheme__versus__.Racket_)"></a>“Scheme” versus “Racket”</h4><p>The old name for Racket was “PLT Scheme,” and the core compiler and
run-time system used to be called “MzScheme.” The old names are
entrenched in Racket internals, to the point that most C bindings
defined in this manual start with <span class="stt">scheme_</span>. In principle, they
all should be renamed to start <span class="stt">racket_</span>.</p><h4 x-source-module="(lib "scribblings/inside/inside.scrbl")" x-part-tag=""Building_Racket_from_Source"">1.2<tt> </tt><a name="(part._.Building_.Racket_from_.Source)"></a>Building Racket from Source</h4><p>The normal Racket distribution includes <span class="stt">".rkt"</span> sources for
collection-based libraries. After modifying library files, run
<span class="stt">raco setup</span> (see <a href="http://download.racket-lang.org/docs/6.1/html/local-redirect/index.html?doc=raco&rel=setup.html&version=6.1" class="Sq" data-pltdoc="x"><span class="stt">raco setup</span>: Installation Management</a>) to rebuild installed
libraries.</p><p>The normal Racket distribution does not include the C sources for
Racket’s run-time system. To build Racket from scratch, download a
source distribution from <a href="http://download.racket-lang.org"><span class="url">http://download.racket-lang.org</span></a>;
detailed build instructions are in the <span class="stt">"README"</span> file in the
top-level <span class="stt">"src"</span> directory. You can also get the latest
sources from the <span class="stt">git</span> repository at
<a href="https://github.com/plt/racket"><span class="url">https://github.com/plt/racket</span></a>, but beware that the repository is
one step away from a normal source distribution, and it provides build
modes that are more suitable for developing Racket itself; see
<span class="stt">"INSTALL.txt"</span> in the <span class="stt">git</span> repository for more
information.</p><h4 x-source-module="(lib "scribblings/inside/inside.scrbl")" x-part-tag=""CGC versus 3m"">1.3<tt> </tt><a name="(part._.C.G.C._versus._3m)"></a>CGC versus 3m</h4><p>Before mixing any C code with Racket, first decide whether to use the
<span style="font-weight: bold">3m</span> variant of Racket, the <span style="font-weight: bold">CGC</span> variant of Racket, or
both:</p><ul><li><p><span style="font-weight: bold"><a name="(idx._(gentag._0._(lib._scribblings/inside/inside..scrbl)))"></a>3m</span> : the main variant of Racket, which uses
<span style="font-style: italic">precise</span> garbage collection and requires explicit
registration of pointer roots and allocation shapes. The precise
garbage collector may move its objects in memory during a
collection.</p></li><li><p><span style="font-weight: bold"><a name="(idx._(gentag._1._(lib._scribblings/inside/inside..scrbl)))"></a>CGC</span> : the original variant of Racket, where
memory management depends on a <span style="font-style: italic">conservative</span> garbage
collector. The conservative garbage collector can automatically find
references to managed values from C local variables and (on some
platforms) static variables, and it does not move allocated
objects.</p></li></ul><p>At the C level, working with CGC can be much easier than working with
3m, but overall system performance is typically better with 3m.</p><h4 x-source-module="(lib "scribblings/inside/inside.scrbl")" x-part-tag=""embedding-and-extending"">1.4<tt> </tt><a name="(part._embedding-and-extending)"></a>Embedding and Extending Racket</h4><p>The Racket run-time system can be embedded into a larger program; see
<a href="embedding.html" data-pltdoc="x">Embedding into a Program</a> for more information. As an alternative to
embedding, the <span class="stt">racket</span> executable can also be run in a
subprocess, and that choice may be better for many purposes. On
Windows, <a href="http://download.racket-lang.org/docs/6.1/html/local-redirect/index.html?tag=%28part._%28.%27%28lib._mzcom%2Fmzcom..scrbl%29.%27._.%27top.%27%29%29&version=6.1" class="Sq" data-pltdoc="x">MzCom</a> provides another option.</p><p>The Racket run-time system <a href="Writing_Racket_Extensions.html" data-pltdoc="x">can
be extended</a> with new C-implemented functions. Historically, writing
an extension could provide performance benefits relative to writing
pure Racket code, but Racket performance has improved to the point
that performance benefits of writing C code (if any) are usually too
small to justify the maintenance effort. For calling functions that
are provided by a C-implemented library, meanwhile, using with
<a href="http://download.racket-lang.org/docs/6.1/html/local-redirect/index.html?doc=foreign&rel=index.html&version=6.1" class="Sq" data-pltdoc="x">foreign-function interface</a>
within Racket is a better choice than writing an extension of Racket
to call the library.</p><h4 x-source-module="(lib "scribblings/inside/inside.scrbl")" x-part-tag=""places"">1.5<tt> </tt><a name="(part._places)"></a>Racket and Places</h4><p>Each Racket <a href="http://download.racket-lang.org/docs/6.1/html/local-redirect/index.html?doc=reference&rel=places.html%23%2528tech._place%2529&version=6.1" class="techoutside Sq" data-pltdoc="x"><span class="techinside">place</span></a> corresponds to a separate OS-implemented
thread. Each place has its own memory manager. Pointers to GC-managed
memory cannot be communicated from one place to another, because such
pointers in one place are invisible to the memory manager of another
place.</p><p>When <a href="http://download.racket-lang.org/docs/6.1/html/local-redirect/index.html?doc=reference&rel=places.html%23%2528tech._place%2529&version=6.1" class="techoutside Sq" data-pltdoc="x"><span class="techinside">place</span></a> support is enabled, static variables at the C level
generally cannot hold pointers to GC-managed memory, since the static
variable may be used from multiple places. For some OSes, a static
variable can be made thread-local, in which case it has a different
address in each OS thread, and each different address can be
registered with the GC for a given place.</p><p>In an <a href="embedding.html" data-pltdoc="x">embedding application</a>, the OS thread that
originally calls <a href="Evaluation.html#%28cpp._scheme_basic_env%29" class="RktStxLink" data-pltdoc="x"><span class="stt">scheme_basic_env</span></a> is the OS thread of the
original place. When <a href="Evaluation.html#%28cpp._scheme_basic_env%29" class="RktStxLink" data-pltdoc="x"><span class="stt">scheme_basic_env</span></a> is called a second time to
reset the interpreter, it can be called in an OS thread that is
different from the original call to
<a href="Evaluation.html#%28cpp._scheme_basic_env%29" class="RktStxLink" data-pltdoc="x"><span class="stt">scheme_basic_env</span></a>. Thereafter, the new thread is the OS thread
for the original place.</p><h4 x-source-module="(lib "scribblings/inside/inside.scrbl")" x-part-tag=""Racket_and_Threads"">1.6<tt> </tt><a name="(part._.Racket_and_.Threads)"></a>Racket and Threads</h4><p>Racket implements threads for Racket programs without aid from the
operating system, so that Racket threads are cooperative from the
perspective of C code. On Unix, stand-alone Racket uses a single
OS-implemented thread. On Windows and Mac OS X, stand-alone
Racket uses a few private OS-implemented threads for background
tasks, but these OS-implemented threads are never exposed by the
Racket API.</p><p>Racket can co-exist with additional OS-implemented threads, but the
additional OS threads must not call any <span class="stt">scheme_</span> function. Only
the OS thread representing a particular <a href="http://download.racket-lang.org/docs/6.1/html/local-redirect/index.html?doc=reference&rel=places.html%23%2528tech._place%2529&version=6.1" class="techoutside Sq" data-pltdoc="x"><span class="techinside">place</span></a> can call
<span class="stt">scheme_</span> functions. (This restriction is stronger than saying all
calls for a given place must be serialized across threads. Racket
relies on properties of specific threads to avoid stack overflow and
garbage collection.) In an <a href="embedding.html" data-pltdoc="x">embedding
application</a>, for the original place, only the OS thread used to call
<a href="Evaluation.html#%28cpp._scheme_basic_env%29" class="RktStxLink" data-pltdoc="x"><span class="stt">scheme_basic_env</span></a> can call <span class="stt">scheme_</span> functions. For any other
place, only the OS thread that is created by Racket for the place can
be used to call <span class="stt">scheme_</span> functions.</p><p>See <a href="threads.html" data-pltdoc="x">Threads</a> for more information about threads, including
the possible effects of Racket’s thread implementation on extension
and embedding C code.</p><h4 x-source-module="(lib "scribblings/inside/inside.scrbl")" x-part-tag=""im:unicode"">1.7<tt> </tt><a name="(part._im~3aunicode)"></a>Racket, Unicode, Characters, and Strings</h4><p>A character in Racket is a Unicode code point. In C, a character
value has type <span class="stt">mzchar</span>, which is an alias for <span class="stt">unsigned</span> —<wbr></wbr>
which is, in turn, 4 bytes for a properly compiled Racket. Thus, a
<span class="stt">mzchar*</span> string is effectively a UCS-4 string.</p><p>Only a few Racket functions use <span class="stt">mzchar*</span>. Instead, most
functions accept <span class="stt">char*</span> strings. When such byte strings are to be
used as a character strings, they are interpreted as UTF-8
encodings. A plain ASCII string is always acceptable in such cases,
since the UTF-8 encoding of an ASCII string is itself.</p><p>See also <a href="im_values_types.html#%28part._im~3astrings%29" data-pltdoc="x">Strings</a> and <a href="im_encodings.html" data-pltdoc="x">String Encodings</a>.</p><h4 x-source-module="(lib "scribblings/inside/inside.scrbl")" x-part-tag=""im:intsize"">1.8<tt> </tt><a name="(part._im~3aintsize)"></a>Integers</h4><p>Racket expects to be compiled in a mode where <span class="stt">short</span> is a
16-bit integer, <span class="stt">int</span> is a 32-bit integer, and <span class="stt">intptr_t</span> has
the same number of bits as <span class="stt">void*</span>. The <span class="stt">long</span> type can match
either <span class="stt">int</span> or <span class="stt">intptr_t</span>, depending on the platform.
The <span class="stt">mzlonglong</span> type has
64 bits for compilers that support a 64-bit integer type, otherwise it
is the same as <span class="stt">intptr_t</span>; thus, <span class="stt">mzlonglong</span> tends to match
<span class="stt">long long</span>. The <span class="stt">umzlonglong</span> type is the unsigned version
of <span class="stt">mzlonglong</span>.</p><div class="navsetbottom"><span class="navleft"><form class="searchform"><input class="searchbox" style="color: #888;" type="text" value="...search manuals..." title="Enter a search string to search the manuals" onkeypress="return DoSearchKey(event, this, "6.1", "../");" onfocus="this.style.color="black"; this.style.textAlign="left"; if (this.value == "...search manuals...") this.value="";" onblur="if (this.value.match(/^ *$/)) { this.style.color="#888"; this.style.textAlign="center"; this.value="...search manuals..."; }"/></form> <a href="../index.html" title="up to the documentation top" data-pltdoc="x" onclick="return GotoPLTRoot("6.1");">top</a></span><span class="navright"> <a href="index.html" title="backward to "Inside: Racket C API"" data-pltdoc="x">← prev</a> <a href="index.html" title="up to "Inside: Racket C API"" data-pltdoc="x">up</a> <a href="embedding.html" title="forward to "2 Embedding into a Program"" data-pltdoc="x">next →</a></span> </div></div></div><div id="contextindicator"> </div></body></html>
|