223cc6685e
git-svn-id: svn://svn.compuextreme.de/Viitor/V963/Viitor_cc65@5933 504e572c-2e33-0410-9681-be2bf7408885
130 lines
5.7 KiB
HTML
130 lines
5.7 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
|
|
<HTML>
|
|
<HEAD>
|
|
<META NAME="GENERATOR" CONTENT="LinuxDoc-Tools 0.9.20">
|
|
<TITLE>ca65 Users Guide: Module constructors/destructors</TITLE>
|
|
<LINK HREF="ca65-16.html" REL=next>
|
|
<LINK HREF="ca65-14.html" REL=previous>
|
|
<LINK HREF="ca65.html#toc15" REL=contents>
|
|
</HEAD>
|
|
<BODY>
|
|
<A HREF="ca65-16.html">Next</A>
|
|
<A HREF="ca65-14.html">Previous</A>
|
|
<A HREF="ca65.html#toc15">Contents</A>
|
|
<HR>
|
|
<H2><A NAME="condes"></A> <A NAME="s15">15.</A> <A HREF="ca65.html#toc15">Module constructors/destructors</A></H2>
|
|
|
|
|
|
<P><EM>Note:</EM> This section applies mostly to C programs, so the explanation
|
|
below uses examples from the C libraries. However, the feature may also be
|
|
useful for assembler programs.</P>
|
|
|
|
|
|
<H2><A NAME="ss15.1">15.1</A> <A HREF="ca65.html#toc15.1">Overview</A>
|
|
</H2>
|
|
|
|
|
|
<P>Using the <CODE>
|
|
<A HREF="ca65-10.html#.CONSTRUCTOR">.CONSTRUCTOR</A></CODE>, <CODE>
|
|
<A HREF="ca65-10.html#.DESTRUCTOR">.DESTRUCTOR</A></CODE> and <CODE>
|
|
<A HREF="ca65-10.html#.INTERRUPTOR">.INTERRUPTOR</A></CODE> keywords it it possible to export functions in a
|
|
special way. The linker is able to generate tables with all functions of a
|
|
specific type. Such a table will <EM>only</EM> include symbols from object
|
|
files that are linked into a specific executable. This may be used to add
|
|
initialization and cleanup code for library modules, or a table of interrupt
|
|
handler functions.</P>
|
|
<P>The C heap functions are an example where module initialization code is used.
|
|
All heap functions (<CODE>malloc</CODE>, <CODE>free</CODE>, ...) work with a few
|
|
variables that contain the start and the end of the heap, pointers to the free
|
|
list and so on. Since the end of the heap depends on the size and start of the
|
|
stack, it must be initialized at runtime. However, initializing these
|
|
variables for programs that do not use the heap are a waste of time and
|
|
memory.</P>
|
|
<P>So the central module defines a function that contains initialization code and
|
|
exports this function using the <CODE>.CONSTRUCTOR</CODE> statement. If (and only if)
|
|
this module is added to an executable by the linker, the initialization
|
|
function will be placed into the table of constructors by the linker. The C
|
|
startup code will call all constructors before <CODE>main</CODE> and all destructors
|
|
after <CODE>main</CODE>, so without any further work, the heap initialization code is
|
|
called once the module is linked in.</P>
|
|
<P>While it would be possible to add explicit calls to initialization functions
|
|
in the startup code, the new approach has several advantages:</P>
|
|
<P>
|
|
<OL>
|
|
<LI>If a module is not included, the initialization code is not linked in and not
|
|
called. So you don't pay for things you don't need.
|
|
</LI>
|
|
<LI>Adding another library that needs initialization does not mean that the
|
|
startup code has to be changed. Before we had module constructors and
|
|
destructors, the startup code for all systems had to be adjusted to call the
|
|
new initialization code.
|
|
</LI>
|
|
<LI>The feature saves memory: Each additional initialization function needs just
|
|
two bytes in the table (a pointer to the function).
|
|
</LI>
|
|
</OL>
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="ss15.2">15.2</A> <A HREF="ca65.html#toc15.2">Calling order</A>
|
|
</H2>
|
|
|
|
|
|
<P>The symbols are sorted in increasing priority order by the linker when using
|
|
one of the builtin linker configurations, so the functions with lower
|
|
priorities come first and are followed by those with higher priorities. The C
|
|
library runtime subroutine that walks over the function tables calls the
|
|
functions starting from the top of the table - which means that functions with
|
|
a high priority are called first.</P>
|
|
<P>So when using the C runtime, functions are called with high priority functions
|
|
first, followed by low priority functions.</P>
|
|
|
|
|
|
<H2><A NAME="ss15.3">15.3</A> <A HREF="ca65.html#toc15.3">Pitfalls</A>
|
|
</H2>
|
|
|
|
|
|
<P>When using these special symbols, please take care of the following:</P>
|
|
<P>
|
|
<UL>
|
|
<LI>The linker will only generate function tables, it will not generate code to
|
|
call these functions. If you're using the feature in some other than the
|
|
existing C environments, you have to write code to call all functions in a
|
|
linker generated table yourself. See the <CODE>condes</CODE> and <CODE>callirq</CODE> modules
|
|
in the C runtime for an example on how to do this.
|
|
</LI>
|
|
<LI>The linker will only add addresses of functions that are in modules linked to
|
|
the executable. This means that you have to be careful where to place the
|
|
condes functions. If initialization or an irq handler is needed for a group of
|
|
functions, be sure to place the function into a module that is linked in
|
|
regardless of which function is called by the user.
|
|
</LI>
|
|
<LI>The linker will generate the tables only when requested to do so by the
|
|
<CODE>FEATURE CONDES</CODE> statement in the linker config file. Each table has to
|
|
be requested separately.
|
|
</LI>
|
|
<LI>Constructors and destructors may have priorities. These priorities determine
|
|
the order of the functions in the table. If your initialization or cleanup code
|
|
does depend on other initialization or cleanup code, you have to choose the
|
|
priority for the functions accordingly.
|
|
</LI>
|
|
<LI>Besides the <CODE>
|
|
<A HREF="ca65-10.html#.CONSTRUCTOR">.CONSTRUCTOR</A></CODE>, <CODE>
|
|
<A HREF="ca65-10.html#.DESTRUCTOR">.DESTRUCTOR</A></CODE> and <CODE>
|
|
<A HREF="ca65-10.html#.INTERRUPTOR">.INTERRUPTOR</A></CODE> statements, there is also a more generic command:
|
|
<CODE>
|
|
<A HREF="ca65-10.html#.CONDES">.CONDES</A></CODE>. This allows to specify an
|
|
additional type. Predefined types are 0 (constructor), 1 (destructor) and 2
|
|
(interruptor). The linker generates a separate table for each type on request.
|
|
</LI>
|
|
</UL>
|
|
</P>
|
|
|
|
|
|
<HR>
|
|
<A HREF="ca65-16.html">Next</A>
|
|
<A HREF="ca65-14.html">Previous</A>
|
|
<A HREF="ca65.html#toc15">Contents</A>
|
|
</BODY>
|
|
</HTML>
|