1
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
2
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
3
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
5
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
6
<meta name="generator" content="AsciiDoc 8.2.2" />
7
<style type="text/css">
9
p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
11
border: 1px solid red;
16
margin: 1em 5% 1em 5%;
21
text-decoration: underline;
39
h1, h2, h3, h4, h5, h6 {
41
font-family: sans-serif;
48
border-bottom: 2px solid silver;
51
border-bottom: 2px solid silver;
61
border: 1px solid silver;
76
font-family: sans-serif;
83
font-family: sans-serif;
87
font-family: sans-serif;
89
border-top: 2px solid silver;
95
padding-bottom: 0.5em;
99
padding-bottom: 0.5em;
103
div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
104
div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
105
div.admonitionblock {
108
margin-bottom: 1.5em;
110
div.admonitionblock {
112
margin-bottom: 2.5em;
115
div.content { /* Block element content. */
119
/* Block element titles. */
120
div.title, caption.title {
121
font-family: sans-serif;
125
margin-bottom: 0.5em;
131
td div.title:first-child {
134
div.content div.title:first-child {
137
div.content + div.title {
141
div.sidebarblock > div.content {
143
border: 1px solid silver;
150
div.listingblock > div.content {
151
border: 1px solid silver;
156
div.quoteblock > div.content {
163
div.verseblock + div.attribution {
167
div.admonitionblock .icon {
171
text-decoration: underline;
173
padding-right: 0.5em;
175
div.admonitionblock td.content {
177
border-left: 2px solid silver;
180
div.exampleblock > div.content {
181
border-left: 2px solid silver;
185
div.verseblock div.content {
189
div.imageblock div.content { padding-left: 0; }
190
div.imageblock img { border: 1px solid silver; }
191
span.image img { border-style: none; }
195
margin-bottom: 0.8em;
207
list-style-position: outside;
210
list-style-type: lower-alpha;
213
div.tableblock > table {
214
border: 3px solid #527bbd;
217
font-family: sans-serif;
226
margin-bottom: 0.8em;
234
padding-right: 0.8em;
241
div#footer-badges { display: none; }
246
font-family: sans-serif;
250
margin-bottom: 0.1em;
253
div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
269
/* Workarounds for IE6's broken and incomplete CSS2. */
271
div.sidebar-content {
273
border: 1px solid silver;
276
div.sidebar-title, div.image-title {
277
font-family: sans-serif;
280
margin-bottom: 0.5em;
283
div.listingblock div.content {
284
border: 1px solid silver;
289
div.quoteblock-content {
293
div.exampleblock-content {
294
border-left: 2px solid silver;
298
/* IE6 sets dynamically generated links as visited. */
299
div#toc a:visited { color: blue; }
301
<title>Global object handlings of SigScheme</title>
305
<h1>Global object handlings of SigScheme</h1>
308
<div class="sectionbody">
309
<p>SigScheme has portable mechanisms that control:</p>
313
global symbols hiding
318
global variable to dynamically allocated variable conversion
322
<p>This document describes its necessity and usage.</p>
324
<h2>2. The problems</h2>
325
<div class="sectionbody">
326
<h3>2.1. Global symbol conflict with other libraries</h3>
327
<p>Since SigScheme uses semi-common <em>scm_</em> and <em>Scm</em> prefixes for exported
328
symbols, it may conflict with other libraries if the client application is also
329
directly or indirectly linked with another Scheme implementation such as
330
libguile. This is a serious problem when implementing a fundamental library
331
based on libsscm, such as libuim.</p>
332
<p>To avoid such conflict, many platforms provide symbol exportation control
333
ability. For example, GNU ld and Windows DLL can handle it based on a optional
334
file which contains the symbol information. And libtool provides an useful
335
option <tt>-export-symbols-regex</tt> for such purpose to make the handlings
336
platform-independent. However, unfortunately libtool does not ensure its
337
portability. Currently supported platforms are considerably limited (at least
338
on version 2.1a 2006-03-30) and some platforms seems that can never be
340
<p>Since primal portability is indispensable value of SigScheme to be being an
341
useful embedded Scheme implementation, we cannot depend on such problematic
342
toolchain-based symbol exportation control.</p>
343
<h3>2.2. Platforms that lack writable static data</h3>
344
<p>Some platforms such as BREW and some versions of Symbian OS lack writable
345
static data capability. It means that no writable global variable can be used
346
in SigScheme. But SigScheme do need various global data such as dynamic extent,
347
symbol table, R5RS constant object holder and so on. So an alternative dynamic
348
data store that can globally be accessed is needed.</p>
351
<div class="sectionbody">
352
<p>The two problems are resolved with two related mechanisms.</p>
353
<p>For the symbol conflict problem, an alternative special compilation method
354
called <em>combined-source mode</em> is provided.</p>
355
<p>It combines all source code of SigScheme into single file, and makes all global
356
objects static. So no symbols will be exposed. A client of libsscm can use this
357
combined version of the library by including the file <tt>sigscheme-combined.c</tt>
358
directly into a C/C++ source of the client. Once it included, all configured
359
SigScheme features can be used as file-local code, and it can also be linked
360
with other arbitrary objects via user-written wrapper.</p>
361
<p>And the writable static data problem is resolved with <em>aggregated global
362
variables</em> mechanism works on the combined-source mode. When this feature is
363
directed, all of the global variables including static ones are aggregated into
364
a single big struct, and allocated to platform-specific global store such as
365
thread local storage or a member variable of application instance. The
366
accessing method to the variables is abstracted by some macros, and any
367
variable can be accessed as if ordinary variable.</p>
368
<p>Finally, a variant configuration of the two mechanisms is also available for
369
the platforms lacking writable static data. It is combined, global variables
370
aggregated, but exports SigScheme's API symbols. This configuration is supposed
371
to provide libsscm on such platforms.</p>
373
<h2>4. Combined-source mode usage for libsscm users</h2>
374
<div class="sectionbody">
375
<h3>4.1. Preparation</h3>
376
<p>The combined-source version of the library is optional and not built by
377
default. Instruct as follows to build it.</p>
378
<div class="listingblock">
379
<div class="content">
380
<pre><tt> $ make -C src combined</tt></pre>
382
<p>It results the file <tt>src/sigscheme-combined.c</tt>. Since the generated code
383
reflects user-configuration, it must be rebuilt every after <tt>configure</tt>.</p>
384
<h3>4.2. Compilation</h3>
385
<p>Include the <tt>sigscheme-combined.c</tt> directly into a C/C++ code, as following
386
example. Ordinary separated compilation and linking does not work because of
387
its "all global objects made static" nature.</p>
388
<div class="listingblock">
389
<div class="title">Example: a C code using combined-source mode of the SigScheme</div>
390
<div class="content">
391
<pre><tt>#include "sigscheme-combined.c"
393
#include <config.h> /* client's own config.h */
395
#include <stdlib.h>
396
#include <stdio.h>
398
#include "my-header.h"
400
<strong>static</strong> ScmObj
401
my_function(<strong>int</strong> val)
403
<strong>return</strong> SCM_MAKE_INT(val * 2);
410
<tt>sigscheme-combined.c</tt> must be included prior to client's own <tt>config.h</tt>
411
since many autoconf-defined macros of SigScheme must appropriately be
412
undefined in the file to avoid conflicting with the client-side ones
417
Add include path to <tt>sigscheme/include</tt> and <tt>sigscheme/src</tt> since the
418
<tt>sigscheme-combined.c</tt> includes various source files in the directories
426
The client code can use all of public SigScheme API defined in
427
<tt>sigscheme.h</tt>, <tt>scmint.h</tt>, <tt>encoding.h</tt>, <tt>global.h</tt> and SigScheme's own
428
<tt>condig.h</tt>. Any other interfaces should not be used even if accessible
433
All of SigScheme's internal macros are undefined and hidden at the end of
434
<tt>sigscheme-combined.c</tt> inclusion, to reduce namespace pollution
439
Many internal variables and functions of SigScheme are exposed to the
440
client code. Be careful of conflict
445
<h2>5. Combined-source mode with exported API symbols</h2>
446
<div class="sectionbody">
447
<p>To export SigScheme API symbols against the combined-source mode, define
448
<tt>SCM_EXPORT_API</tt> to 1 prior to including the <tt>sigscheme-combined.c</tt>, as
449
follows. See <tt>src/dllentry.c</tt> as real example.</p>
450
<div class="listingblock">
451
<div class="title">Example: instructs that export SigScheme API</div>
452
<div class="content">
453
<pre><tt>#define SCM_EXPORT_API 1
454
#include "sigscheme-combined.c"</tt></pre>
457
<h2>6. Non-static functions handling for SigScheme developers</h2>
458
<div class="sectionbody">
459
<p>To control global symbol exportation, any non-static function declaration and
460
definition need little modification. For both prototype declaration and actual
461
definition, prepend <tt>SCM_EXPORT</tt> to the function. There is no distinction
462
between public API and library-internal API on the exportation control. Use
463
<tt>SCM_EXPORT</tt> for both type of functions.</p>
464
<p>The <tt>SCM_EXPORT</tt> macro is replaced with <tt>static</tt> when the combined-source mode
465
without <tt>SCM_EXPORT_API</tt>.</p>
466
<div class="listingblock">
467
<div class="title">Example: symbol exportation control for functions</div>
468
<div class="content">
469
<pre><tt><i>/* declaration */</i>
470
SCM_EXPORT <strong>void</strong> scm_set_lib_path(<strong>const</strong> <strong>char</strong> *path);
471
SCM_EXPORT ScmObj scm_p_load(ScmObj filename);
473
<i>/* definition */</i>
474
SCM_EXPORT <strong>void</strong>
475
scm_set_lib_path(<strong>const</strong> <strong>char</strong> *path)
481
scm_p_load(ScmObj filename)
487
<h2>7. Global variables handling for SigScheme developers</h2>
488
<div class="sectionbody">
489
<p>The aggregated variables mechanism is mainly provided for SigScheme developers
490
and used to write libsscm. All global variables used in SigScheme must be
491
written with this mechanism to keep portable to the embedded
492
platforms. Although it tries to keep original usage of the global variables,
493
some rewrite of source codes declaring and defining the variables are needed
494
because of the limitation of C macro ability.</p>
495
<h3>7.1. Constant global variables</h3>
496
<p>Constant global variables can safely be used in all platforms regardless of
497
whether static or not. But a little modification of <tt>extern</tt> declaration is
498
needed for the combined-source mode treatment.</p>
499
<p>Be careful about all part of the variables are certainly qualified as
501
<div class="listingblock">
502
<div class="title">Example: a constant global variables declaration and definition</div>
503
<div class="content">
504
<pre><tt><i>/* declaration */</i>
505
<strong>extern</strong> <strong>const</strong> <strong>char</strong> *<strong>const</strong> names[];
507
<i>/* definition */</i>
508
<strong>const</strong> <strong>char</strong> *<strong>const</strong> names[] = {
512
<strong>static</strong> <strong>const</strong> <strong>char</strong> *<strong>const</strong> other_names[] = {
516
<div class="listingblock">
517
<div class="title">Example: rewritten declaration and definition</div>
518
<div class="content">
519
<pre><tt><i>/* declaration */</i>
520
SCM_EXTERN(<strong>const</strong> <strong>char</strong> *<strong>const</strong> names[]);
522
<i>/* definition */</i>
523
<strong>const</strong> <strong>char</strong> *<strong>const</strong> names[] = {
527
<strong>static</strong> <strong>const</strong> <strong>char</strong> *<strong>const</strong> other_names[] = {
531
<h3>7.2. Writable extern variables</h3>
532
<p>Writable and exported global variables need more complex rewriting.</p>
533
<div class="listingblock">
534
<div class="title">Example: a writable extern variables declaration and definition</div>
535
<div class="content">
536
<pre><tt><i>/* declaration */</i>
537
<strong>extern</strong> <strong>int</strong> foo bar;
538
<strong>extern</strong> ScmObj obj_a, obj_b;
539
<strong>extern</strong> <strong>void</strong> (*func)(<strong>void</strong>);
541
<i>/* definition */</i>
542
<strong>int</strong> foo bar;
544
<strong>void</strong> (*func)(<strong>void</strong>);</tt></pre>
546
<div class="listingblock">
547
<div class="title">Example: rewritten declaration and definition</div>
548
<div class="content">
549
<pre><tt><i>/* declaration */</i>
550
SCM_GLOBAL_VARS_BEGIN(srfi99);
551
<strong>int</strong> foo bar;
553
<strong>void</strong> (*func)(<strong>void</strong>);
554
SCM_GLOBAVARS_END(srfi99);
555
#define foo SCM_GLOBAL_VAR(srfi99, foo)
556
#define bar SCM_GLOBAL_VAR(srfi99, bar)
557
#define obj_a SCM_GLOBAL_VAR(srfi99, obj_a)
558
#define obj_b SCM_GLOBAL_VAR(srfi99, obj_b)
559
#define func SCM_GLOBAL_VAR(srfi99, func)
561
<i>/* definition */</i>
562
SCM_DEFINE_EXPORTED_VARS(srfi99);</tt></pre>
564
<p>The identifier <em>srfi99</em> in above example specifies a namespace and
565
aggregational unit which the variables are placed into. It is recommended that
566
the name is taken from the filename which the definition is placed.</p>
567
<p>The macros defined immediately after the SCM_GLOBAVARS_END() are conventional
568
accessors for the variables. The proper accessing method for the variables is
569
SCM_GLOBAL_VAR(namespace, varname), but it unacceptably bothers code
570
writing. So such macros should be defined. The macros make rewriting of codes
571
operate on the variables unneeded. The SCM_GLOBAL_VAR() allows being accessed
573
<p>But since it may obviously cause unexpected replacement if any of the names are
574
appeared as a non-global-variable object in a code, such as local variable or
575
struct member. The macro definition may affect to all source files even if the
576
header defines the macro is not included by a file, because of the unified
577
translation unit formed by the combined-source. To avoid such unwanted
578
replacement, The variable names should be prefixed to be unique over all
580
<div class="listingblock">
581
<div class="title">Example: prefixing each variables is recommended</div>
582
<div class="content">
583
<pre><tt><i>/* declaration */</i>
584
SCM_GLOBAL_VARS_BEGIN(srfi99);
585
<strong>int</strong> scm_foo scm_bar;
586
ScmObj scm_obj_a, scm_obj_b;
587
<strong>void</strong> (*scm_func)(<strong>void</strong>);
588
SCM_GLOBAVARS_END(srfi99);
589
#define scm_foo SCM_GLOBAL_VAR(srfi99, scm_foo)
590
#define scm_bar SCM_GLOBAL_VAR(srfi99, scm_bar)
591
#define scm_obj_a SCM_GLOBAL_VAR(srfi99, scm_obj_a)
592
#define scm_obj_b SCM_GLOBAL_VAR(srfi99, scm_obj_b)
593
#define scm_func SCM_GLOBAL_VAR(srfi99, scm_func)
595
<i>/* definition */</i>
596
SCM_DEFINE_EXPORTED_VARS(srfi99);</tt></pre>
598
<p>Finally, conditional compilation is allowed even if in the declaration.</p>
599
<div class="listingblock">
600
<div class="title">Example: conditional compilation is allowed</div>
601
<div class="content">
602
<pre><tt><i>/* declaration */</i>
603
SCM_GLOBAL_VARS_BEGIN(srfi99);
604
<strong>int</strong> scm_foo scm_bar;
605
#<strong>if</strong> SCM_USE_FOO
606
ScmObj scm_obj_a, scm_obj_b;
607
<strong>void</strong> (*scm_func)(<strong>void</strong>);
609
SCM_GLOBAVARS_END(srfi99);
610
#define scm_foo SCM_GLOBAL_VAR(srfi99, scm_foo)
611
#define scm_bar SCM_GLOBAL_VAR(srfi99, scm_bar)
612
#define scm_obj_a SCM_GLOBAL_VAR(srfi99, scm_obj_a)
613
#define scm_obj_b SCM_GLOBAL_VAR(srfi99, scm_obj_b)
614
#define scm_func SCM_GLOBAL_VAR(srfi99, scm_func)
616
<i>/* definition */</i>
617
SCM_DEFINE_EXPORTED_VARS(srfi99);</tt></pre>
619
<h3>7.3. Static variables</h3>
620
<p>Static variables handling is similar to external one, but some additional
621
treatment is needed.</p>
622
<div class="listingblock">
623
<div class="title">Example: a static variables definition</div>
624
<div class="content">
625
<pre><tt><strong>static</strong> <strong>int</strong> foo bar;
626
<strong>static</strong> ScmObj obj_a, obj_b;
627
<strong>static</strong> <strong>void</strong> (*func)(<strong>void</strong>);</tt></pre>
629
<div class="listingblock">
630
<div class="title">Example: rewritten definition</div>
631
<div class="content">
632
<pre><tt>SCM_GLOBAL_VARS_BEGIN(static_srfi99);
633
#define <strong>static</strong>
634
<strong>static</strong> <strong>int</strong> l_foo l_bar;
635
<strong>static</strong> ScmObj l_obj_a, l_obj_b;
636
<strong>static</strong> <strong>void</strong> (*l_func)(<strong>void</strong>);
637
#undef <strong>static</strong>
638
SCM_GLOBAL_VARS_END(static_srfi99);
639
#define l_foo SCM_GLOBAL_VAR(static_srfi99, l_foo)
640
#define l_bar SCM_GLOBAL_VAR(static_srfi99, l_bar)
641
#define l_obj_a SCM_GLOBAL_VAR(static_srfi99, l_obj_a)
642
#define l_obj_b SCM_GLOBAL_VAR(static_srfi99, l_obj_b)
643
#define l_func SCM_GLOBAL_VAR(static_srfi99, l_func)
644
SCM_DEFINE_STATIC_VARS(static_srfi99);</tt></pre>
646
<p>The technical difference to external one is:</p>
650
Use SCM_DEFINE_STATIC_VARS() instead of SCM_DEFINE_EXPORTED_VARS() to
651
define declared variables
655
<p>And some more conventions:</p>
659
Enclose the declaration with <tt>#define static</tt> and <tt>#undef static</tt> to keep
660
indicating that the variables are static
665
The <tt>static</tt> specifier is technically not allowed here
670
The <tt>#define</tt> and <tt>#undef</tt> must be placed inside
671
<tt>SCM_GLOBAL_VARS_{BEGIN,END}()</tt>. Placing outside of them makes the
679
The namespace should be prefixed with <tt>static_</tt>
684
The variable names should be prefixed with <tt>l_</tt> (stands for <em>local</em>)
688
<h3>7.4. Common restrictions</h3>
722
<tt>aggregated_*</tt>
728
<h3>7.5. Initialization and finalization</h3>
729
<p>The aggregated variables <strong>MUST</strong> be initialized with <tt>SCM_GLOBAL_VARS_INIT()</tt>
730
prior to being used. Before the initialization, accessing the variables is
731
completely invalid. It is not only containing unspecified value but may cause
732
crash on some platforms since the storage is not allocated yet.</p>
733
<div class="listingblock">
734
<div class="title">Example: initialization of a set of variables</div>
735
<div class="content">
736
<pre><tt><strong>void</strong>
737
scm_srfi99_init(<strong>void</strong>)
739
SCM_GLOBAL_VARS_INIT(srfi99);
740
SCM_GLOBAL_VARS_INIT(static_srfi99);
743
<p>After the initialization, the variables contained in the namespace specified by
744
the <tt>SCM_GLOBAL_VARS_INIT()</tt> are allocated and zero-cleared. If you want that
745
an variable is initialized, assign the value by hand after the
746
initialization. Load-time initialization is not allowed and technically does
748
<div class="listingblock">
749
<div class="title">Example: initialization is not allowed (and does not work)</div>
750
<div class="content">
751
<pre><tt>SCM_GLOBAL_VARS_BEGIN(static_srfi99);
752
#define <strong>static</strong>
753
<strong>static</strong> <strong>int</strong> l_foo = 100;
754
#undef <strong>static</strong>
755
SCM_GLOBAL_VARS_END(static_srfi99);</tt></pre>
757
<p>The by-function initialization ensures that cyclic finalization ->
758
re-initialization loop works properly without careful initial value treatment
759
of global variables. It is helpful to ensure that SigScheme is
760
re-initialization safe.</p>
761
<p>Finalization macro is also provided and usable. But since it is currently empty
762
expression on all platforms, and most code modules do not have finalization
763
function, no finalization is performed for global variables to keep footprint
764
shrunk. But the macro should be added if a code module has finalization
766
<div class="listingblock">
767
<div class="title">Example: finalization of the variables</div>
768
<div class="content">
769
<pre><tt><strong>void</strong>
770
scm_srfi99_fin(<strong>void</strong>)
772
SCM_GLOBAL_VARS_FIN(srfi99);
773
SCM_GLOBAL_VARS_FIN(static_srfi99);
778
<div id="footer-text">
779
Last updated 17-May-2008 12:45:37 JST
added
removed
sigscheme/doc/global-obj.html
