-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathmanual.html
1207 lines (1106 loc) · 55.5 KB
/
manual.html
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
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
<!-- 2025-01-24 Fri 10:55 -->
<meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Clasp Manual</title>
<meta name="author" content="Alex Wood" />
<meta name="generator" content="Org Mode" />
<style>
#content { max-width: 60em; margin: auto; }
.title { text-align: center;
margin-bottom: .2em; }
.subtitle { text-align: center;
font-size: medium;
font-weight: bold;
margin-top:0; }
.todo { font-family: monospace; color: red; }
.done { font-family: monospace; color: green; }
.priority { font-family: monospace; color: orange; }
.tag { background-color: #eee; font-family: monospace;
padding: 2px; font-size: 80%; font-weight: normal; }
.timestamp { color: #bebebe; }
.timestamp-kwd { color: #5f9ea0; }
.org-right { margin-left: auto; margin-right: 0px; text-align: right; }
.org-left { margin-left: 0px; margin-right: auto; text-align: left; }
.org-center { margin-left: auto; margin-right: auto; text-align: center; }
.underline { text-decoration: underline; }
#postamble p, #preamble p { font-size: 90%; margin: .2em; }
p.verse { margin-left: 3%; }
pre {
border: 1px solid #e6e6e6;
border-radius: 3px;
background-color: #f2f2f2;
padding: 8pt;
font-family: monospace;
overflow: auto;
margin: 1.2em;
}
pre.src {
position: relative;
overflow: auto;
}
pre.src:before {
display: none;
position: absolute;
top: -8px;
right: 12px;
padding: 3px;
color: #555;
background-color: #f2f2f299;
}
pre.src:hover:before { display: inline; margin-top: 14px;}
/* Languages per Org manual */
pre.src-asymptote:before { content: 'Asymptote'; }
pre.src-awk:before { content: 'Awk'; }
pre.src-authinfo::before { content: 'Authinfo'; }
pre.src-C:before { content: 'C'; }
/* pre.src-C++ doesn't work in CSS */
pre.src-clojure:before { content: 'Clojure'; }
pre.src-css:before { content: 'CSS'; }
pre.src-D:before { content: 'D'; }
pre.src-ditaa:before { content: 'ditaa'; }
pre.src-dot:before { content: 'Graphviz'; }
pre.src-calc:before { content: 'Emacs Calc'; }
pre.src-emacs-lisp:before { content: 'Emacs Lisp'; }
pre.src-fortran:before { content: 'Fortran'; }
pre.src-gnuplot:before { content: 'gnuplot'; }
pre.src-haskell:before { content: 'Haskell'; }
pre.src-hledger:before { content: 'hledger'; }
pre.src-java:before { content: 'Java'; }
pre.src-js:before { content: 'Javascript'; }
pre.src-latex:before { content: 'LaTeX'; }
pre.src-ledger:before { content: 'Ledger'; }
pre.src-lisp:before { content: 'Lisp'; }
pre.src-lilypond:before { content: 'Lilypond'; }
pre.src-lua:before { content: 'Lua'; }
pre.src-matlab:before { content: 'MATLAB'; }
pre.src-mscgen:before { content: 'Mscgen'; }
pre.src-ocaml:before { content: 'Objective Caml'; }
pre.src-octave:before { content: 'Octave'; }
pre.src-org:before { content: 'Org mode'; }
pre.src-oz:before { content: 'OZ'; }
pre.src-plantuml:before { content: 'Plantuml'; }
pre.src-processing:before { content: 'Processing.js'; }
pre.src-python:before { content: 'Python'; }
pre.src-R:before { content: 'R'; }
pre.src-ruby:before { content: 'Ruby'; }
pre.src-sass:before { content: 'Sass'; }
pre.src-scheme:before { content: 'Scheme'; }
pre.src-screen:before { content: 'Gnu Screen'; }
pre.src-sed:before { content: 'Sed'; }
pre.src-sh:before { content: 'shell'; }
pre.src-sql:before { content: 'SQL'; }
pre.src-sqlite:before { content: 'SQLite'; }
/* additional languages in org.el's org-babel-load-languages alist */
pre.src-forth:before { content: 'Forth'; }
pre.src-io:before { content: 'IO'; }
pre.src-J:before { content: 'J'; }
pre.src-makefile:before { content: 'Makefile'; }
pre.src-maxima:before { content: 'Maxima'; }
pre.src-perl:before { content: 'Perl'; }
pre.src-picolisp:before { content: 'Pico Lisp'; }
pre.src-scala:before { content: 'Scala'; }
pre.src-shell:before { content: 'Shell Script'; }
pre.src-ebnf2ps:before { content: 'ebfn2ps'; }
/* additional language identifiers per "defun org-babel-execute"
in ob-*.el */
pre.src-cpp:before { content: 'C++'; }
pre.src-abc:before { content: 'ABC'; }
pre.src-coq:before { content: 'Coq'; }
pre.src-groovy:before { content: 'Groovy'; }
/* additional language identifiers from org-babel-shell-names in
ob-shell.el: ob-shell is the only babel language using a lambda to put
the execution function name together. */
pre.src-bash:before { content: 'bash'; }
pre.src-csh:before { content: 'csh'; }
pre.src-ash:before { content: 'ash'; }
pre.src-dash:before { content: 'dash'; }
pre.src-ksh:before { content: 'ksh'; }
pre.src-mksh:before { content: 'mksh'; }
pre.src-posh:before { content: 'posh'; }
/* Additional Emacs modes also supported by the LaTeX listings package */
pre.src-ada:before { content: 'Ada'; }
pre.src-asm:before { content: 'Assembler'; }
pre.src-caml:before { content: 'Caml'; }
pre.src-delphi:before { content: 'Delphi'; }
pre.src-html:before { content: 'HTML'; }
pre.src-idl:before { content: 'IDL'; }
pre.src-mercury:before { content: 'Mercury'; }
pre.src-metapost:before { content: 'MetaPost'; }
pre.src-modula-2:before { content: 'Modula-2'; }
pre.src-pascal:before { content: 'Pascal'; }
pre.src-ps:before { content: 'PostScript'; }
pre.src-prolog:before { content: 'Prolog'; }
pre.src-simula:before { content: 'Simula'; }
pre.src-tcl:before { content: 'tcl'; }
pre.src-tex:before { content: 'TeX'; }
pre.src-plain-tex:before { content: 'Plain TeX'; }
pre.src-verilog:before { content: 'Verilog'; }
pre.src-vhdl:before { content: 'VHDL'; }
pre.src-xml:before { content: 'XML'; }
pre.src-nxml:before { content: 'XML'; }
/* add a generic configuration mode; LaTeX export needs an additional
(add-to-list 'org-latex-listings-langs '(conf " ")) in .emacs */
pre.src-conf:before { content: 'Configuration File'; }
table { border-collapse:collapse; }
caption.t-above { caption-side: top; }
caption.t-bottom { caption-side: bottom; }
td, th { vertical-align:top; }
th.org-right { text-align: center; }
th.org-left { text-align: center; }
th.org-center { text-align: center; }
td.org-right { text-align: right; }
td.org-left { text-align: left; }
td.org-center { text-align: center; }
dt { font-weight: bold; }
.footpara { display: inline; }
.footdef { margin-bottom: 1em; }
.figure { padding: 1em; }
.figure p { text-align: center; }
.equation-container {
display: table;
text-align: center;
width: 100%;
}
.equation {
vertical-align: middle;
}
.equation-label {
display: table-cell;
text-align: right;
vertical-align: middle;
}
.inlinetask {
padding: 10px;
border: 2px solid gray;
margin: 10px;
background: #ffffcc;
}
#org-div-home-and-up
{ text-align: right; font-size: 70%; white-space: nowrap; }
textarea { overflow-x: auto; }
.linenr { font-size: smaller }
.code-highlighted { background-color: #ffff00; }
.org-info-js_info-navigation { border-style: none; }
#org-info-js_console-label
{ font-size: 10px; font-weight: bold; white-space: nowrap; }
.org-info-js_search-highlight
{ background-color: #ffff00; color: #000000; font-weight: bold; }
.org-svg { }
</style>
<link rel="stylesheet" type="text/css" href="styles/readtheorg/css/htmlize.css"/><link rel="stylesheet" type="text/css" href="styles/readtheorg/css/readtheorg.css"/><script src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.3/jquery.min.js"></script><script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.4/js/bootstrap.min.js"></script><script type="text/javascript" src="styles/lib/js/jquery.stickytableheaders.min.js"></script><script type="text/javascript" src="styles/readtheorg/js/readtheorg.js"></script>
</head>
<body>
<div id="preamble" class="status">
<div id="top-menu">
<ul>
<li><a href="index.html">Clasp</a>
<ul>
<li><a href="news.html">News</a></li>
<li><a href="download.html">Download</a></li>
</ul></li>
<li><a href="index.html">Doc</a>
<ul>
<li><a href="license.html">License</a></li>
<li><a href="manual.html">Manual</a></li>
<li><a href="building.html">Building</a></li>
<li><a href="clbind-doc.html">Exposing C++ Libraries</a></li>
</ul></li>
<li><a href="index.html">Misc</a>
<ul>
<li><a href="community.html">Community</a></li>
<li><a href="projects.html">Projects</a></li>
<li><a href="media.html">Media</a></li>
<li><a href="acknowlegements.html">Acknowledgements</a></li>
</ul></li>
</ul>
</div>
</div>
<div id="content" class="content">
<h1 class="title">Clasp Manual</h1>
<div id="table-of-contents" role="doc-toc">
<h2>Table of Contents</h2>
<div id="text-table-of-contents" role="doc-toc">
<ul>
<li><a href="#orga0c7d20">1. Introduction</a>
<ul>
<li><a href="#org7c305c3">1.1. Conformance</a></li>
<li><a href="#org0593848">1.2. Distribution</a></li>
<li><a href="#org5f8a7df">1.3. Building</a></li>
<li><a href="#org0da5b65">1.4. Contributing</a></li>
<li><a href="#org02aec25">1.5. Credits</a></li>
</ul>
</li>
<li><a href="#org0ec8abd">2. Starting and Stopping</a></li>
<li><a href="#orgf48f546">3. Lisp</a>
<ul>
<li><a href="#org9a8293c">3.1. Evaluation and Compilation</a></li>
<li><a href="#orga6c469d">3.2. Types and Classes</a>
<ul>
<li><a href="#org07246e6">3.2.1. Disjointness</a></li>
</ul>
</li>
<li><a href="#org45a45ad">3.3. Data and Control Flow</a></li>
<li><a href="#org36b0865">3.4. Iteration</a></li>
<li><a href="#org19cc97d">3.5. Objects</a>
<ul>
<li><a href="#orgb9e9d39">3.5.1. Metaobject Protocol</a></li>
<li><a href="#org7da3acf">3.5.2. Generic function dispatch efficiency</a></li>
<li><a href="#org6157fe5">3.5.3. Miscellany</a></li>
</ul>
</li>
<li><a href="#org317aaa9">3.6. Structures</a></li>
<li><a href="#orgb8aabdd">3.7. Conditions</a></li>
<li><a href="#orgff59aab">3.8. Symbols</a></li>
<li><a href="#org05f0493">3.9. Packages</a></li>
<li><a href="#orga015640">3.10. Numbers</a></li>
<li><a href="#orgca58f61">3.11. Characters</a></li>
<li><a href="#orgf8619f3">3.12. Conses</a></li>
<li><a href="#org39ae6b2">3.13. Arrays</a></li>
<li><a href="#org0ffaa93">3.14. Strings</a></li>
<li><a href="#orgc2fdf12">3.15. Sequences</a>
<ul>
<li><a href="#org2083348">3.15.1. Extensible Sequences</a></li>
</ul>
</li>
<li><a href="#org808c9e2">3.16. Hash Tables</a></li>
<li><a href="#org8cebe85">3.17. Filenames</a></li>
<li><a href="#org8b2f91f">3.18. Files</a></li>
<li><a href="#org26ac30a">3.19. Streams</a>
<ul>
<li><a href="#org1684136">3.19.1. Gray streams</a></li>
</ul>
</li>
<li><a href="#orgba02f72">3.20. Printer</a></li>
<li><a href="#org85f13e0">3.21. Reader</a></li>
<li><a href="#org563ce55">3.22. System Construction</a></li>
<li><a href="#org38f1fea">3.23. Environment</a>
<ul>
<li><a href="#orgc61246d">3.23.1. Stepper</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#orgbc21741">4. C++ Interface (clbind)</a></li>
<li><a href="#orga5b38bd">5. Foreign Function Interface</a></li>
<li><a href="#orgda813fc">6. REPL</a></li>
<li><a href="#orge670187">7. Debug interface</a></li>
<li><a href="#org8b07d65">8. Multiprocessing</a>
<ul>
<li><a href="#org3c00ed3">8.1. Processes</a></li>
<li><a href="#org70e328d">8.2. Special variables</a></li>
<li><a href="#org69b788b">8.3. Mutexes</a></li>
<li><a href="#org421abb5">8.4. Shared Mutexes</a></li>
<li><a href="#org48cab55">8.5. Condition Variables</a></li>
<li><a href="#org73a5092">8.6. Memory Model</a></li>
<li><a href="#org87b49c6">8.7. Atomics</a></li>
<li><a href="#orgea21694">8.8. Compare-and-swap</a></li>
<li><a href="#org7d1123e">8.9. Fences</a></li>
</ul>
</li>
<li><a href="#org6c1467a">9. Introspection</a></li>
<li><a href="#org0593e63">10. Sockets</a></li>
<li><a href="#orgdd77ef0">11. Serve Event</a></li>
<li><a href="#orgab7bd5a">12. Garbage Collection</a></li>
<li><a href="#orgf2544ea">13. POSIX</a>
<ul>
<li><a href="#orga2d7c52">13.1. Signal Handling</a></li>
<li><a href="#org851b419">13.2. Further posix interfaces</a></li>
</ul>
</li>
</ul>
</div>
</div>
<div id="outline-container-orga0c7d20" class="outline-2">
<h2 id="orga0c7d20"><span class="section-number-2">1.</span> Introduction</h2>
<div class="outline-text-2" id="text-1">
<p>
Clasp is an implementation of Common Lisp primarily designed for compatibility with C++-language programs and libraries.
</p>
<p>
Note that Clasp is a work in progress, as is this manual.
</p>
</div>
<div id="outline-container-org7c305c3" class="outline-3">
<h3 id="org7c305c3"><span class="section-number-3">1.1.</span> Conformance</h3>
<div class="outline-text-3" id="text-1-1">
<p>
Clasp conforms with the requirements of ANSI INCITS 226-1994 (R2004) with some exceptions, listed below in the "Lisp" section. Any deviation from the standard not listed there is a bug, and should be reported (see "Contributing").
</p>
</div>
</div>
<div id="outline-container-org0593848" class="outline-3">
<h3 id="org0593848"><span class="section-number-3">1.2.</span> Distribution</h3>
<div class="outline-text-3" id="text-1-2">
<p>
At present, the developers do not make Clasp binaries available. Clasp is open source, and available on-line at <a href="https://github.com/clasp-developers/clasp">https://github.com/clasp-developers/clasp</a>.
</p>
</div>
</div>
<div id="outline-container-org5f8a7df" class="outline-3">
<h3 id="org5f8a7df"><span class="section-number-3">1.3.</span> Building</h3>
<div class="outline-text-3" id="text-1-3">
<p>
See <a href="building.html">Building</a>.
</p>
</div>
</div>
<div id="outline-container-org0da5b65" class="outline-3">
<h3 id="org0da5b65"><span class="section-number-3">1.4.</span> Contributing</h3>
<div class="outline-text-3" id="text-1-4">
<p>
Check <a href="community.html">the community page</a> for instructions on contributing to Clasp.
</p>
<p>
Discussions of Clasp development are mostly carried out on Freenode's #clasp channel.
</p>
</div>
</div>
<div id="outline-container-org02aec25" class="outline-3">
<h3 id="org02aec25"><span class="section-number-3">1.5.</span> Credits</h3>
<div class="outline-text-3" id="text-1-5">
<p>
Clasp is the project of <a href="https://thirdlaw.tech">Dr. Christian Schafmeister</a>. Additional contributions have been made by <a href="https://github.com/yitzchak">Tarn W. Burton</a>, <a href="https://github.com/kpoeck">Karsten Poeck</a>, <a href="https://github.com/Bike">Alex Wood</a>, and many other contributors as seen in the Git history.
</p>
<p>
Clasp's source code is derived substantially from that of Embeddable Common Lisp. Code from SBCL and SICL has been incorporated as well. Most notably, the compiler is SICL's Cleavir compiler with some minor customizations.
</p>
</div>
</div>
</div>
<div id="outline-container-org0ec8abd" class="outline-2">
<h2 id="org0ec8abd"><span class="section-number-2">2.</span> Starting and Stopping</h2>
<div class="outline-text-2" id="text-2">
<p>
The Clasp executable accepts many different command line arguments. You can get the most up to date summary by passing <code>--help</code>. Here are some important ones:
</p>
<ul class="org-ul">
<li><code>--noinform</code>: Skip messages at startup.</li>
<li><code>--noprint</code>: Start a read-eval loop instead of a read-eval-print loop, and don't prompt. This is intended for scripts (e.g. piping a list of forms to Clasp).</li>
<li><code>--disable-debugger</code>: Set things up so that if the default debugger would be entered, Clasp quits with a backtrace and nonzero exit status instead. <code>*debugger-hook*</code> and <code>ext:*invoke-debugger-hook*</code> (below) work as usual, i.e. this setting does not affect them.</li>
<li><code>--non-interactive</code>: Rather than starting a REPL, quit. This is intended to be used with <code>--eval</code> and <code>--load</code>. Implies <code>--disable-debugger</code>.</li>
<li><code>--feature feature</code>: Intern "feature" as a keyword and push it to <code>*features*</code>.</li>
<li><code>--eval form</code>: Evaluate the given form. <code>--eval</code> and <code>--load</code> options are processed in order from left to right.</li>
<li><code>--load filename</code>: <code>cl:load</code> the given file. Intended for convenience, since <code>--eval (load ...)</code> could involve annoying quotation issues.</li>
<li><code>--norc</code>: Do not load <code>~/.clasprc</code> (see below).</li>
</ul>
<p>
If the file <code>~/.clasprc</code> exists, Clasp will <code>cl:load</code> it before processing <code>--eval</code> and <code>--load</code> options and starting the REPL.
</p>
<p>
To exit Clasp, the <code>ext:quit</code> function can be used. If provided an integer argument, it's used as the exit status; the default is zero.
</p>
</div>
</div>
<div id="outline-container-orgf48f546" class="outline-2">
<h2 id="orgf48f546"><span class="section-number-2">3.</span> Lisp</h2>
<div class="outline-text-2" id="text-3">
<p>
Clasp is an implementation of <a href="https://en.wikipedia.org/wiki/Common_Lisp">ANSI Common Lisp</a>. The following subsections detail intentional deviations from the standard,
some extensions to standard functionality,
and notes on optimizing Lisp programs to run well within Clasp.
(Extensions not closely related to standard systems are explained in their own sections below.)
</p>
</div>
<div id="outline-container-org9a8293c" class="outline-3">
<h3 id="org9a8293c"><span class="section-number-3">3.1.</span> Evaluation and Compilation</h3>
<div class="outline-text-3" id="text-3-1">
<p>
Clasp expands compiler macros essentially unconditionally.
That is, provided the operator is not declared <code>notinline</code>,
the compiler will attempt to expand compiler macros.
If compiler macroexpansion signals, this signal will be recorded and reported by the compiler.
If compiler macroexpansion errors out, the compiler will abandon expansion and use the unexpanded form,
while noting the error for display.
</p>
<p>
<code>ext:with-current-source-form</code> is a useful macro to allow error messages from macroexpanders and compiler-macro-expanders to have more specific source information. See its docstring for more information.
</p>
</div>
</div>
<div id="outline-container-orga6c469d" class="outline-3">
<h3 id="orga6c469d"><span class="section-number-3">3.2.</span> Types and Classes</h3>
<div class="outline-text-3" id="text-3-2">
<p>
<code>typep</code> calls can be efficiently compiled only if the second argument, the type specifier, is constant.
Clasp's compiler will process the type specifier and generate code to check for objects of that type
directly, avoiding the usual runtime cost of interpreting the type.
</p>
<p>
Types defined by <code>deftype</code> use a "type expander" function analogous to a macro expander function.
A type expander is a function of two arguments, a type specifier and an environment. When called on an appropriate specifier and environment, it computes and returns another type specifier. Type expanders are accessible through the <code>ext:type-expander</code> accessor.
</p>
</div>
<div id="outline-container-org07246e6" class="outline-4">
<h4 id="org07246e6"><span class="section-number-4">3.2.1.</span> Disjointness</h4>
<div class="outline-text-4" id="text-3-2-1">
<p>
Unless otherwise specified, types Clasp defines as extensions can be considered to be in a disjointness
relationship with standard and other extension types, as in CLHS 4.2.2 "Type Relationships".
That is, if Clasp defines a type <code>foo</code>, you can assume that <code>foo</code> is not a subtype of <code>hash-table</code>,
or <code>cons</code>, or so on, and vice versa, unless it is explicitly stated to be.
But just as in 4.2.2, Clasp extension types may be subtypes of <code>structure-object</code> or <code>standard-object</code>
without this being explicitly noted here.
</p>
</div>
</div>
</div>
<div id="outline-container-org45a45ad" class="outline-3">
<h3 id="org45a45ad"><span class="section-number-3">3.3.</span> Data and Control Flow</h3>
<div class="outline-text-3" id="text-3-3">
<p>
<code>defsetf</code>, <code>define-setf-expander</code> etc. define a "setf expander" function analogous to a macro expander
function. A setf expander is a function of two arguments, a place and an environment.
When called an appropriate place and environment, the expander computes and returns the values used by
<code>setf</code>. Setf expanders are accessible through the <code>ext:setf-expander</code> accessor.
</p>
</div>
</div>
<div id="outline-container-org36b0865" class="outline-3">
<h3 id="org36b0865"><span class="section-number-3">3.4.</span> Iteration</h3>
<div class="outline-text-3" id="text-3-4">
<p>
<code>loop</code> supports iteration over general sequences (see below) through a for-as-sequence subclause.
This is identical to the subclause in SBCL.
The syntax is <code>being {each | the} {element | elements} {of | in}</code>.
For example, <code>(loop for x being each element in '(1 2 3) do (print x))</code>.
</p>
</div>
</div>
<div id="outline-container-org19cc97d" class="outline-3">
<h3 id="org19cc97d"><span class="section-number-3">3.5.</span> Objects</h3>
<div class="outline-text-3" id="text-3-5">
<p>
CLOS, as part of Common Lisp, is fully supported.
</p>
</div>
<div id="outline-container-orgb9e9d39" class="outline-4">
<h4 id="orgb9e9d39"><span class="section-number-4">3.5.1.</span> Metaobject Protocol</h4>
<div class="outline-text-4" id="text-3-5-1">
<p>
The Metaobject Protocol, as described in <a href="http://metamodular.com/CLOS-MOP/">AMOP</a>, is supported.
Undocumented deviations from AMOP are bugs and should be reported, as with the CL standard.
</p>
<p>
Symbols relating to MOP are exported from the "CLOS" package.
</p>
</div>
</div>
<div id="outline-container-org7da3acf" class="outline-4">
<h4 id="org7da3acf"><span class="section-number-4">3.5.2.</span> Generic function dispatch efficiency</h4>
<div class="outline-text-4" id="text-3-5-2">
<p>
Clasp uses a new system for generic function dispatch designed by Dr. Robert Strandh.
[Paper reference goes here.] Essentially, after a few calls to a generic function,
a just-in-time compiler will install a discriminating function for it that can pass control to the
correct effective method very efficiently. This means that calls with arguments that all have the same
specializers as those of a previous call will in general be more efficient.
</p>
<p>
For some applications, the specializers a function will be called with are known beforehand,
and the runtime overhead of the just-in-time compilation would be unfortunate.
Clasp defines an interface to take care of most of the compilation early: The <code>clos:satiate</code> function.
See its docstring for more info.
</p>
</div>
</div>
<div id="outline-container-org6157fe5" class="outline-4">
<h4 id="org6157fe5"><span class="section-number-4">3.5.3.</span> Miscellany</h4>
<div class="outline-text-4" id="text-3-5-3">
<p>
A consequence of the dispatch method described above is that obsolete instances are updated as soon as
they are used as an argument to any generic function call - not just to slot accessors.
This is allowed by the standard, but may surprise some programmers.
</p>
</div>
</div>
</div>
<div id="outline-container-org317aaa9" class="outline-3">
<h3 id="org317aaa9"><span class="section-number-3">3.6.</span> Structures</h3>
</div>
<div id="outline-container-orgb8aabdd" class="outline-3">
<h3 id="orgb8aabdd"><span class="section-number-3">3.7.</span> Conditions</h3>
<div class="outline-text-3" id="text-3-7">
<p>
In addition to <code>cl:restart-name</code>, Clasp provides some readers to introspect about restarts,
for advanced users (e.g. writing your own debugger, or the <a href="https://github.com/Shinmera/dissect">Dissect</a> library):
<code>ext:restart-function</code> returns the function called by <code>cl:invoke-restart</code>, and <code>ext:report-function</code>,
<code>ext:interactive-function</code>, and <code>ext:interactive-function</code> return the corresponding arguments in
<code>cl:restart-bind</code>. These will always be appropriate functions, so for example <code>ext:report-function</code> will
always return a function of one stream argument, but if no <code>:report-function</code> was provided it will report
the restart in Clasp's default way. The identities of these returned functions cannot be relied on,
i.e. they may not be identical to those provided to <code>cl:restart-bind</code>.
</p>
<p>
There is also <code>ext:restart-associated-conditions</code>, which returns a list of conditions associated
(by <code>cl:with-condition-restarts</code>) with the restart in the current dynamic environment.
</p>
</div>
</div>
<div id="outline-container-orgff59aab" class="outline-3">
<h3 id="orgff59aab"><span class="section-number-3">3.8.</span> Symbols</h3>
</div>
<div id="outline-container-org05f0493" class="outline-3">
<h3 id="org05f0493"><span class="section-number-3">3.9.</span> Packages</h3>
<div class="outline-text-3" id="text-3-9">
<p>
Clasp supports package-local nicknames, through an interface based on that of SBCL's.
A package-local nickname is a nickname for a package that is only active when some other package is in
place as <code>*package*</code>. For example, if the package "FOO" has "B" as a package-local nickname for package
"BAR", then while <code>*package*</code> is the <code>foo</code> package, the prefix "B:" will be read as if it was "BAR:".
</p>
<p>
Local nicknames may be specified in <code>defpackage</code> through the <code>(:local-nicknames (nickname package-name)*)</code>
extended options. <code>nickname</code> must be a string designator and <code>package-name</code> a package designator - both
are unevaluated. The functions <code>ext:package-local-nicknames</code>, <code>ext:add-package-local-nickname</code>,
<code>ext:remove-package-local-nickname</code>, and <code>ext:package-locally-nicknamed-by-list</code> can be used for a more
programmatic interface.
</p>
</div>
</div>
<div id="outline-container-orga015640" class="outline-3">
<h3 id="orga015640"><span class="section-number-3">3.10.</span> Numbers</h3>
<div class="outline-text-3" id="text-3-10">
<p>
There are two types of floats, <code>single-float</code> and <code>double-float</code>. <code>short-float</code> is synonymous with the
former and <code>long-float</code> is synonymous with the latter, per the standard's requirements.
<code>single-float</code> is in the IEEE754 binary32 (single) format, and <code>double-float</code> in binary64 (double) format.
The representation of a float as bits can be interconverted with a float using the functions
<code>ext:single-float-to-bits</code>, <code>bits-to-single-float</code>, <code>double-float-to-bits</code>, and <code>bits-to-double-float</code>.
These functions take or return nonnegative integers;
for example <code>(logbitp 31 (ext:single-floats-to-bit float))</code> returns whether the sign bit is set.
</p>
</div>
</div>
<div id="outline-container-orgca58f61" class="outline-3">
<h3 id="orgca58f61"><span class="section-number-3">3.11.</span> Characters</h3>
<div class="outline-text-3" id="text-3-11">
<p>
Clasp supports Unicode by default. <code>code-char</code> and <code>char-code</code> work with Unicode codepoints.
Unicode character names are also supported, e.g. <code>(princ #\GREEK_SMALL_LETTER_LAMDA) -> λ</code>.
=(defun λ(n)(* 2 n)) (λ 32) -> 64=is also possible.
</p>
<p>
Type <code>character</code> includes all characters in Unicode. Type <code>base-char</code> includes only single byte
characters, i.e. Basic Latin and Latin-1 Supplement.
</p>
</div>
</div>
<div id="outline-container-orgf8619f3" class="outline-3">
<h3 id="orgf8619f3"><span class="section-number-3">3.12.</span> Conses</h3>
</div>
<div id="outline-container-org39ae6b2" class="outline-3">
<h3 id="org39ae6b2"><span class="section-number-3">3.13.</span> Arrays</h3>
<div class="outline-text-3" id="text-3-13">
<p>
In Clasp, arrays with no fill-pointer, displacement, or express adjustability are simple
(as in <code>simple-array</code>), and arrays that have any of these are not.
Additionally, Clasp implements multidimensional arrays - even ones that are simple in this sense - as
if they were displaced to an underlying one dimensional array.
As such, it is most efficient to work with one-dimensional simple arrays directly.
</p>
</div>
</div>
<div id="outline-container-org0ffaa93" class="outline-3">
<h3 id="org0ffaa93"><span class="section-number-3">3.14.</span> Strings</h3>
</div>
<div id="outline-container-orgc2fdf12" class="outline-3">
<h3 id="orgc2fdf12"><span class="section-number-3">3.15.</span> Sequences</h3>
<div class="outline-text-3" id="text-3-15">
</div>
<div id="outline-container-org2083348" class="outline-4">
<h4 id="org2083348"><span class="section-number-4">3.15.1.</span> Extensible Sequences</h4>
<div class="outline-text-4" id="text-3-15-1">
<p>
<a href="https://doi.org/10.1145/1622123.1622138">The extensible sequences protocol developed by Christophe Rhodes</a> is supported.
Symbols related to the protocol are external in Clasp's "SEQUENCE" package.
This protocol allows programmers to define their own sequence classes that work efficiently with standard
Common Lisp functions. It is recommended that programmers consult other resources,
such as Dr. Rhodes' paper, for more information on how to use this protocol effectively.
</p>
<p>
To summarize: Programmers wishing to make a custom sequence class must ensure their class has
<code>cl:sequence</code> as a superclass. (Note that <code>sequence</code> is itself abstract, so if a custom class needs to
have e.g. slots, it should also be a subclass of <code>standard-object</code> or something like it.)
Methods on <code>elt</code>, <code>(setf elt)</code>, <code>length</code> applicable to objects of the class must be defined for any
sequence functions to work; an applicable method on <code>make-sequence-like</code> must be defined for creation
of this sequence to work; and an applicable method on <code>adjust-sequence</code> must be defined for destructive
operations to work. Standard sequence functions will then operate correctly with these sequences,
as will <code>make-sequence</code> and <code>coerce</code>.
</p>
<p>
For efficiency, programmers may also define applicable methods on <code>make-sequence-iterator</code>,
or less efficiently but more simply, on <code>make-simple-sequence-iterator</code>, <code>iterator-step</code>, <code>iterator-endp</code>,
<code>iterator-element</code>, <code>(setf iterator-element)</code>, <code>iterator-index</code>, and <code>iterator-copy</code>.
</p>
<p>
Note that because the <code>sequence:</code> generic function cognates to <code>cl:</code> sequence functions are defined to
have the same behavior in almost all cases, Clasp takes the view that they need not be called.
For example, a call to <code>cl:find</code> with a custom sequence object <span class="underline">may</span> result in a call to <code>sequence:find</code>,
but may not. In other words the cognates are considered optional, and only possibly useful for
optimization. This is still in flux. If you think it's a bad idea, contact a maintainer to talk.
</p>
<p>
As a small extension to the extension, if a custom sequence object does not implement enough of the
protocol for a sequence function to complete, it will signal an error of type
<code>sequence:protocol-unimplemented</code>. The reader <code>sequence:protocol-unimplemented-operation</code> can be used to
get the name of the operation that failed from these conditions.
</p>
</div>
</div>
</div>
<div id="outline-container-org808c9e2" class="outline-3">
<h3 id="org808c9e2"><span class="section-number-3">3.16.</span> Hash Tables</h3>
<div class="outline-text-3" id="text-3-16">
<p>
<code>make-hash-table</code> supports additional keyword arguments.
</p>
<p>
<code>:weakness</code> can be used to indicate that the garbage collection may collect individual hash table entries
even when the hash table itself is live, in certain circumstances. At present, only weak-key hash tables
are supported: when the weakness argument is <code>:key</code>, the hash table's reference to the key of a table
entry is <span class="underline">weak</span>, and if there are no non-weak references to a key, it is collectable.
See the "Garbage Collection" section below for more information on weak references.
If the weakness parameter is passed as <code>nil</code>, or not passed, the hash table does not contain weak references.
</p>
<p>
<code>:thread-safe</code> can be used to make hash table access safe across multiple threads.
If a thread-safe argument is not passed, or <code>nil</code> is passed, the hash table cannot safely be written to
or read from multiple threads simultaneously (see "Memory Model", below, for a brief explanation of
terminology). If the thread-safe argument is true, the implementation will ensure that accesses can be
carried out from multiple threads simultaneously safely. This does impose a small performance penalty,
which is why it is not the default.
</p>
<p>
If a <code>:test</code> other than a standard equality predicate is passed, <code>:hash-function</code> must be specified as
well. The hash function should be a designator for a function of one argument that is analogous to
<code>sxhash</code>, i.e. <code>(funcall test x y)</code> implies <code>(</code> (funcall hash-function x) (funcall hash-function y))=
and so on. This will create a "custom" hash table that can be used with the standard hash table functions
like <code>gethash</code>, with the exception that at the moment, attempting to dump a custom hash table has
undefined consequences.
</p>
</div>
</div>
<div id="outline-container-org8cebe85" class="outline-3">
<h3 id="org8cebe85"><span class="section-number-3">3.17.</span> Filenames</h3>
</div>
<div id="outline-container-org8b2f91f" class="outline-3">
<h3 id="org8b2f91f"><span class="section-number-3">3.18.</span> Files</h3>
<div class="outline-text-3" id="text-3-18">
<p>
<code>ext:rmdir</code> deletes a directory. <code>EXT:RMTREE</code> deletes an entire directory tree.
</p>
</div>
</div>
<div id="outline-container-org26ac30a" class="outline-3">
<h3 id="org26ac30a"><span class="section-number-3">3.19.</span> Streams</h3>
<div class="outline-text-3" id="text-3-19">
</div>
<div id="outline-container-org1684136" class="outline-4">
<h4 id="org1684136"><span class="section-number-4">3.19.1.</span> Gray streams</h4>
<div class="outline-text-4" id="text-3-19-1">
<p>
The Gray stream interface as described in ANSI committee issue "STREAM-DEFINITION-BY-USER"
(readable, e.g., <a href="http://www.nhplace.com/kent/CL/Issues/stream-definition-by-user.html">on Kent Pitman's website</a>) is supported. Symbols are exported from package "GRAY".
We recommend programmers use a multi-implementation compatibility layer such as <a href="https://common-lisp.net/project/trivial-gray-streams/">trivial-gray-streams</a>
rather than use Clasp's implementation directly.
</p>
<p>
Gray streams allow programmers to define their own stream classes with custom behavior that work with
standard Common Lisp functions. It is recommended that programmers consult another resource, such as the
trivial-gray-streams documentation, for more information on how to use this interface effectively.
</p>
</div>
</div>
</div>
<div id="outline-container-orgba02f72" class="outline-3">
<h3 id="orgba02f72"><span class="section-number-3">3.20.</span> Printer</h3>
<div class="outline-text-3" id="text-3-20">
<p>
When <code>format</code>'s control string argument is constant, the compiler will process it early, so that the
runtime doesn't have to. This improves runtime speed but increases code size.
</p>
</div>
</div>
<div id="outline-container-org85f13e0" class="outline-3">
<h3 id="org85f13e0"><span class="section-number-3">3.21.</span> Reader</h3>
</div>
<div id="outline-container-org563ce55" class="outline-3">
<h3 id="org563ce55"><span class="section-number-3">3.22.</span> System Construction</h3>
</div>
<div id="outline-container-org38f1fea" class="outline-3">
<h3 id="org38f1fea"><span class="section-number-3">3.23.</span> Environment</h3>
<div class="outline-text-3" id="text-3-23">
</div>
<div id="outline-container-orgc61246d" class="outline-4">
<h4 id="orgc61246d"><span class="section-number-4">3.23.1.</span> Stepper</h4>
<div class="outline-text-4" id="text-3-23-1">
<p>
<code>cl:step</code> can be used to step through compiled code as partially described in the standard.
Currently, the stepper can only stop on forms that happen to be compiled as calls, though this may be
improved in the future.
</p>
<p>
Code is steppable if it is compiled with <code>debug 3</code> optimization settings, or is within the <code>step</code> macro.
While unsteppable code is being executed, the stepper will not stop.
</p>
<p>
Clasp further defines some aspects of stepping for the sake of editor/debugger integration.
When the stepper pauses execution, a condition of type <code>cl:step</code> is passed to the debugger.
This condition will print with the source form for the call.
Similarly to <code>cl:break</code>, <code>*debugger-hook*</code> is bound to <code>nil</code>, but <code>ext:*invoke-debugger-hook*</code>
(described below) can still be used for interception. The following restarts are available from a <code>step</code>
condition:
</p>
<ul class="org-ul">
<li><code>cl:continue</code>: Continue without stepping. The stepper will not invoke the debugger again.</li>
<li><code>clasp-debug:step-into</code>: Continue stepping. If the function to be called is steppable,
the stepper will pause within it, and otherwise stepping will proceed after the call.</li>
<li><code>clasp-debug:step-over</code>: Continue stepping, but not into the call the stepper is on.
Stepping will proceed after the call is exited (either by normal return or a non-local exit).</li>
</ul>
</div>
</div>
</div>
</div>
<div id="outline-container-orgbc21741" class="outline-2">
<h2 id="orgbc21741"><span class="section-number-2">4.</span> C++ Interface (clbind)</h2>
<div class="outline-text-2" id="text-4">
<p>
<a href="clbind-doc.html">Documented here.</a>
</p>
</div>
</div>
<div id="outline-container-orga5b38bd" class="outline-2">
<h2 id="orga5b38bd"><span class="section-number-2">5.</span> Foreign Function Interface</h2>
<div class="outline-text-2" id="text-5">
<p>
Clasp can interact with C programs and libraries through its Foreign Function Interface (FFI).
Symbols relating to this interface are external in package "CLASP-FFI".
However, it is recommended for most applications that you use a cross-implementation wrapper layer,
specifically <a href="https://cffi.common-lisp.dev/">CFFI</a>. Clasp's own interface has not yet been documented.
</p>
</div>
</div>
<div id="outline-container-orgda813fc" class="outline-2">
<h2 id="orgda813fc"><span class="section-number-2">6.</span> REPL</h2>
<div class="outline-text-2" id="text-6">
<p>
Clasp's built in read-eval-print loop supports various commands in addition to evaluating Lisp forms.
These commands consist of lines beginning with a Lisp keyword, followed possibly by additional arguments.
The most up to date documentation for this interface is the on-line help system,
obtainable with the command <code>:help</code>.
</p>
<p>
Clasp has a built in debugger, which will be entered by <code>invoke-debugger</code> by default.
<code>:help</code> can describe the debugger commands as well. Some basic commands are <code>:b</code> to print a backtrace,
<code>:rN</code> to invoke the Nth restart, <code>:v</code> to print local variables in the frame, and <code>:up</code>, <code>:down</code>,
and <code>:go</code> for navigating frames.
</p>
<p>
In addition to the standard <code>*debugger-hook*</code>, Clasp has <code>ext:*invoke-debugger-hook*</code>.
This is a similar hook function, but it will be tried before <code>*debugger-hook*</code>, and importantly,
will be called even for <code>break</code> (which binds <code>*debugger-hook*</code> to <code>nil</code> per the standard).
This can be used to set up your own debugger in an IDE.
</p>
<p>
In the debugger, the function <code>ext:tpl-frame</code> can be used to return a representation of the current frame
suitable for the programmatic debug interface described below, and <code>ext:tpl-argument</code> and
<code>ext:tpl-arguments</code> can be used to retrieve arguments.
</p>
<p>
In some applications, it's useful for the program to exit rather than exit a debugger.
The functions <code>ext:disable-debugger</code> and <code>ext:enable-debugger</code> can be used to set whether the debugger
will be entered. These only affect the <b><b>built in</b></b> debugger, and they do not affect <code>*debugger-hook*</code>
or <code>ext:*invoke-debugger-hook*</code>.
</p>
</div>
</div>
<div id="outline-container-orge670187" class="outline-2">
<h2 id="orge670187"><span class="section-number-2">7.</span> Debug interface</h2>
<div class="outline-text-2" id="text-7">
<p>
For advanced users, such as those developing development tools such as debuggers to use with Clasp,
a programmatic interface to debug information is provided by the <code>CLASP-DEBUG</code> package.
</p>
<p>
The <code>with-stack</code> and <code>call-with-stack</code> operators allow <code>frame</code> objects, representing part of the current
control stack, to be interrogated. These frame objects have several readers: <code>frame-function</code>,
<code>frame-arguments</code>, <code>frame-locals</code>, <code>frame-source-position</code>, and <code>frame-language</code>.
More specific information about the function can be obtained with <code>frame-function-name</code>,
<code>frame-function-lambda-list</code>, <code>frame-function-source-position</code>, <code>frame-function-form</code>,
<code>frame-function-documentation</code>, and <code>disassemble-frame</code>.
</p>
<p>
Note that frames necessarily have dynamic extent, because the local variables, arguments, and functions
they refer to may be dynamic-extent themselves.
</p>
<p>
To navigate frames smoothly, a notion of "visibility" exists. Frames can be "invisible" if they aren't of
interest to users. This includes things like internal system code. Of course, the concept of visiblity
can change. Frame visibility is controlled by the <code>*frame-filters*</code> variable, which holds a list of
function designators: a frame is visible if none of the functions return a true value when given the
frame as an argument. As such, all frames are considered visible if <code>*frame-filters*</code> is bound to <code>nil</code>.
</p>
<p>
<code>up</code> and <code>down</code> can be used to navigate visible frames, while <code>frame-up</code> and <code>frame-down</code> ignore
visibility. <code>map-stack</code>, <code>list-stack</code>, and <code>map-indexed-stack</code> can be used to perform manipulations on
all frames at once.
</p>
<p>
<code>with-truncated-stack</code> and <code>with-capped-stack</code> can be used as hints to <code>with-stack</code>
(and therefore debuggers) that only a portion of the control stack is of interest. For example, a
function that signals an error can use <code>with-truncated-stack</code> to ensure that lower debugger frames are
not included in backtraces.
</p>
<p>
<code>print-backtrace</code> is provided as a simple way to print a current backtrace, without needing to use
<code>with-stack</code> and the other more detailed operators.
</p>
</div>
</div>
<div id="outline-container-org8b07d65" class="outline-2">
<h2 id="org8b07d65"><span class="section-number-2">8.</span> Multiprocessing</h2>
<div class="outline-text-2" id="text-8">
<p>
Multiprocessing is supported. Symbols relating to multiprocessing are exported from the "MP" package.
It is recommended that programmers use the <a href="https://github.com/sionescu/bordeaux-threads">Bordeaux-Threads</a> compatibility library rather than Clasp's
interface directly when possible.
</p>
</div>
<div id="outline-container-org3c00ed3" class="outline-3">
<h3 id="org3c00ed3"><span class="section-number-3">8.1.</span> Processes</h3>
<div class="outline-text-3" id="text-8-1">
<p>
A process is a Lisp object representing a distinct thread of execution. Each process evaluates a call to
a Lisp function, and exits when that call would finally return values. Processes have names for debugging
purposes. Processes are "nascent" or "not yet started" if they haven't yet begun evaluating, "active"
if they have begun evaluating, "suspended" if that evaluation has been paused by <code>process-suspend</code>,
and "exited" if they have finished evaluation (normally or by aborting).
</p>
<p>
Processes have type <code>process</code>. <code>make-process</code> creates a new process but does not start it.
<code>process-start</code> enables a process, and <code>process-run-function</code> both creates and enables a process.
The name of a process can be retrieved with <code>process-name</code>. <code>process-active-p</code> can be used to query
whether a process is active. <code>process-suspend</code>, <code>process-resume</code>, <code>interrupt-process</code>, and
<code>process-kill</code> interfere with a process's evaluation. <code>process-join</code> waits until a process until it
completes, and then returns the values its function returned, or signals an error of
type <code>process-join-error</code> if the process ended abnormally. Within a process, <code>exit-process</code> can be used
to end the process's evaluation immediately, and <code>abort-process</code> to do so abnormally; in either case the
dynamic environment is properly unwound. <code>all-processes</code> gets a list of all enabled processes.
The variable <code>*current-process*</code> is bound in any process to that process. Consult the docstrings of
these functions for more information.
</p>
</div>
</div>
<div id="outline-container-org70e328d" class="outline-3">
<h3 id="org70e328d"><span class="section-number-3">8.2.</span> Special variables</h3>
<div class="outline-text-3" id="text-8-2">
<p>
Bindings of special variables (by <code>let</code>, <code>progv</code>, lambda lists, etc.) are thread-local.
That is, executing a binding form for a variable will not affect that variable's value in other threads.
The global value - from <code>symbol-value</code> - is, in contrast, shared between threads.
</p>
</div>
</div>
<div id="outline-container-org69b788b" class="outline-3">
<h3 id="org69b788b"><span class="section-number-3">8.3.</span> Mutexes</h3>
<div class="outline-text-3" id="text-8-3">
<p>
A mutex (short for "MUTual EXclusion"), or lock, can be used to control access to a shared resource by
multiple processes.
</p>
<p>
Mutexes have type <code>mutex</code>. A mutex is created with <code>make-lock</code>, or <code>make-recursive-mutex</code> for a recursive
mutex. <code>get-lock</code> and <code>giveup-lock</code> obtain and release exclusion on a mutex, respectively.
<code>mutex-name</code> retrieves any name of a mutex given at creation.