aboutsummaryrefslogtreecommitdiffstats
path: root/lib/erl_interface/src/README.internal
diff options
context:
space:
mode:
authorErlang/OTP <[email protected]>2009-11-20 14:54:40 +0000
committerErlang/OTP <[email protected]>2009-11-20 14:54:40 +0000
commit84adefa331c4159d432d22840663c38f155cd4c1 (patch)
treebff9a9c66adda4df2106dfd0e5c053ab182a12bd /lib/erl_interface/src/README.internal
downloadotp-84adefa331c4159d432d22840663c38f155cd4c1.tar.gz
otp-84adefa331c4159d432d22840663c38f155cd4c1.tar.bz2
otp-84adefa331c4159d432d22840663c38f155cd4c1.zip
The R13B03 release.OTP_R13B03
Diffstat (limited to 'lib/erl_interface/src/README.internal')
-rw-r--r--lib/erl_interface/src/README.internal285
1 files changed, 285 insertions, 0 deletions
diff --git a/lib/erl_interface/src/README.internal b/lib/erl_interface/src/README.internal
new file mode 100644
index 0000000000..c1f2d6863f
--- /dev/null
+++ b/lib/erl_interface/src/README.internal
@@ -0,0 +1,285 @@
+******************************************************************************
+ 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 ****************************************