******************************************************************************
General
******************************************************************************
There are two different interfaces, the old 'erl_interface' and 'ei'.
The old interface is to depend on the new one, not the other way arount.
Erl_interface should be "thread safe", i.e. you should be able to
handle connections, convert data etc from different threads.
Ei should be "reentrant" or "async safe", i.e. no locks should be set
so that if an ei function is called inside an signal handler there
could be a deadlock.
VxWorks call the operating processes "tasks". These are to be handled the
same way as Unix threads, i.e. there can only be one C node for all tasks
using the old interface.
Try to keep the documented functions, variables and symbols in sync
between
* Documentation
* ei.h and erl_interface.h
* prog/ei_fake_prog.c and prog/erl_fake_prog.c
From time to time do a
% (cd src; gmake check)
(FIXME this check should be rewritten to a test case)
******************************************************************************
Directories
******************************************************************************
* src/aux/
Support files for configure described in the next section
* src/legacy/
Old erl_interface stuff FIXME what about thread support etc....?
* src/connect/
Create nodes, connections, communication with the other node etc
* src/decode/
Simple decode functions
* src/encode/
Simple encode functions
* src/epmd/
Handle communication with epmd
* src/registry/
Key/value database with optional mnesia back up
* src/misc/
The rest of the library
* src/prog/
erl_call and some test programs for compiling and linking
* src/not_used/
Strange, some files are not used....
******************************************************************************
Configuration support files
******************************************************************************
The build uses GNU configure and libtool. The libtool and autoconf
package don't need to be installed to configure and build the
sources. But in "maintainer mode" you need them to update some files
in the source distribution.
* configure.in
Used in maintainer mode together with "aclocal.m4" to create
"configure". "configure.in" is hand written and only need to
be updated when you change the sources to use new header files
or C compiler features. You may get some hints about what to
update using a recent autoconf package and do
% cd erl_inteface
% autoscan src
The result to compare with the current "configure.in" will be
stored in "src/configure.scan".
* aclocal.m4
This file contains macros generated by ??? appended
with the content of "libtool.m4" in the installed libtool
package. (FIXME don't know when this is to be updated and
why it contains so much).
* src/aux/config.guess
* src/aux/config.sub
Used by "configure" to form the subdirectory name
"cpu-vendor-os".
* src/aux/install-sh*
Used if no other BSD compatible install script is found.
* src/aux/config.h.in
Used by "configure" as a template for the resulting
"src/config.h". The file "config.h.in" should be
updated when "configure.in" is updated because the
new macros used in your source and this is the file
where they are listed. You can find out what to update
using
% autoheader
* ltmain.sh
This is XXX (FIXME what?)
The base for the configure.in script was created with 'autoscan'.
The base for the config.h.in file was created with 'autoheader'.
******************************************************************************
Writing source
******************************************************************************
C files in "registry" are considered users of 'ei' and should not
include "eidef.h" or "config.h", only "ei.h".
C files in "prog" could include "config.h" directly.
Other C files should include "eidef.h" as the first line of
source. "eidef.h" contains some common constants and macros and
also includes config.h.
In general avoid including other header files from header files.
The exception is to make the protoypes complete to the user of
this library, i.e. to include <stdio.h> to defined FILE or
to include "ei_x_encode" to define the type ei_x_buff.
The function ei_decode_term() (FIXME encode_term?) work on ETERM,
i.e. it converts between the old erl_interface format and ei.
Because of this it is really part of the erl_interface library,
not the ei library.
Use uint8, uint16, uint32, int8, int16, and int32 for types
where size matters ;-) Use uint8 for buffers where we construct
messages.
NOTE!!!! Sending a "char" to macros like isupper(), isalpha() where
the character is > 127 will cause serios problems on some
machines/OS. The reason is that
'char' may be unsigned, i.e. the Swedish char '�' will
as a number be negativ.
The implementation of isupper() and others will on some
machines use an array that is indexed with the incoming
character code. The Swedish '�' will then create an access
on memory outside the array!
This may give a random value as a result or a segmentation
violation error.
******************************************************************************
Global variables
******************************************************************************
There are two reasons we avoid global variables:
- It is much easier to support threads without them
- On operating systems like VxWorks the global variable is global
to all operating system processes.
There are a few global variables that are ok
ei_x_extra This is set to 100 in "ei_x_encode.c" but can be
changed for debugging the memory allocation.
ei_trace_distribution Enable verbose tracing on stderr.
errno In the non threaded version of the lib this
is a global variable.
__erl_errno This is a global handled by "ei_pthreads.c"
You can check for globals using something like
% nm -g ei_fake_prog | fgrep OBJT
Global variables but with local scope
erl_if_ec Global state, is ok
******************************************************************************
The "long long" story
******************************************************************************
There are some functions in the 'ei' library that uses the GCC and
VC++ "long long" type. Unfortunately this can lead to some trouble.
When user code is linked with the "libei.a" the linker will extract
all objects files needed for resolving all symbol referenses
found. This means that you want to follow the rule that
* To reduce executable code size we use resonably small C source
files. One C file is one object file.
* We try to avoid unessesary dependency. For example currently almost all
ei_x_encode*() functions are in the same object file. Because they all
use the corresponding ei_encode*() function this means using one ei_x
function we will link in "ei_x_encode.o" object file but also all the
"ei_encode*.o" object files even if they are not used.
But the above is not the real trouble, memory and disk is cheap these
days. The real trouble is if we compile the 'ei' library using one
compiler, usually GNU cc, and link with another linker than GNU ld or
miss some runtime libraries that the GNU cc generated object files
assume is on the target. For example currently on Solaris some "long
long" operations will create a dependency to a "hidden" library
"libgcc.a". For example in a library not released got references to
"libgcc.a" '__ashldi3'
% nm -A libei.a | grep '__ashldi3'
libei.a[decode_longlong.o]: [6] | 0| 0|NOTY |GLOB |0 |UNDEF |__ashldi3
libei.a[decode_ulonglong.o]: [5] | 0| 0|NOTY |GLOB |0 |UNDEF |__ashldi3
We can accept that a dependecy is created for code linked with
"libei.a" that actually use 'ei' long long functions. But if we
arrange the 'ei' source badly using a non "long long" functions from
'ei' will still link in an object file that need "libgcc.a". One
example is that in plain R9C the ei_x_encode_longlong() function is
located in the file "ei_x_encode.c". So if any "long long" ei_x
function is used we have an unessesary dependency on
"ei_encode_longlong.o" and then need to link with GNU ld on with the
user code or explicitely link with "libgcc.a". The situation can be
visible in in plain R9C using
% nm -A erl_interface-3.4/lib/libei.a | \
grep 'longlong' | fgrep -v 'longlong.o'
As an possibly alternative to the current solution we may include the
object files inside the "libgcc.a" archive in the "libei.a" archive.
The "libgcc.a" that is assumed to be used when linking can be found
using
% gcc -print-libgcc-file-name
Some links about problems and solutions using "libgcc.a"
http://www.gnu.org/software/gcc/gcc-3.0/libgcc.html
http://www.gnu.org/software/libc/FAQ.html
The license for "libgcc.a" is a bit special and not located on the
official sites. You have to look in the source file for the "libgcc.a"
you use. The file is named "libgcc.c". If you don't know what gcc that
was used for the build of for example 'r9c' you can use
% otp_build_env -o r9c | perl -ne '/(gcc-[\d\.]+)/ and print "$1\n"'
Then to view the lincense do
% less `find /usr/local/share/src/gcc-REL/ -name "libgcc*.c"`
********************************* EOF ****************************************
