0. Preliminary Notes

The porting layer is a work-in-progress and is not yet shaped nicely. Currently it consists of quite heterogeneous pieces (APR extensions, logger, encoder, utility templates etc) which do not form unified interface.

1. Design Notes

The porting layer design adheres to concepts of APR (Apache Portable Runtime libraries), specifically: Detailed APIs mainly follow the APR standard, but there may not be strict correspondence in signatures. Pure C should be used for implementation.

2. Directory structure

Porting functionality is split to several groups: atomics, file I/O, mempools, etc. Each group has a base directory, which contains subdirectories with actual code. These subdirectories are named after the platforms and/or architectures they are compiled on. If there is a strong dependency on both OS and machine architecture, the subdirectory name should combine both. The current directory structure looks as follows: 
port
|->build
|->doc
|->include
|  ->tl
 ->src
  |->atomic
  | |->linux
  | |->linux_ipf
  |  ->win
  |->barriers
  |  ->linux_ipf
  |->crash_handler
  | |->em64t
  | |->ia32
  | |->include
  | |->ipf
  | |->linux
  | |  ->include
  |  ->win
  |->disasm
  | |->linux
  |  ->win
  |->encoder
  |  ->ia32_em64t
  |->file_io
  | |->linux
  |  ->win
  |->lil
  |  ->em64t
  |->logger
  |->malloc
  |->memaccess
  | |->linux
  |  ->win
  |->misc
  | |->linux
  |  ->win
  |->modules
  | |->linux
  |  ->win
  |->signals
  | |->include
  | |->linux
  |  ->win
  |->thread
  | |->linux
  |  ->win
  |->time
  |->tl
   ->vmem
    |->linux
     ->win

Public headers are kept in a separate base directory named include/. Implementation headers may be kept in the source directories.

3. Memory management

The port layer contains wrappers for standard memory allocation functions in the port_malloc.h file. They are presented as defines with names like STD_MALLOC for malloc, STD_FREE for free etc. By default, they are simply equal to relative functions, but if _MEMMGR is defined, they are replaced with another set of functions like port_malloc, port_free etc. These functions provide additional functionality at the expense of lower performance.

Newly provided features:

Instructions on using these features

To switch on allocation and de-allocation logging, define the _MEMMGR_LOG macro. This macro also enables double free calling notifications.

For the final not freed memory reporting, define the _MEMMGR_REPORT macro.

Currently, the stress memory allocator is defined not yet implemented, and just redirects to standard malloc. To switch on stress allocation, define the STRESS_MALLOC macro.

The memory management module cannot use port logging because it leads to infinite recursion. Its own primitive logging system uses the file in the current directory with name malloc.log for both logging and reporting. A different file name and location can be defining MALLOC_LOG_FILE_NAME.

Used memory could be obtained by means of the java.lang.management interface. It is presented as non-heap memory pool with name Native Memory Pool. Different pool name could be set by redefining NATIVE_POOL_NAME.

4. Build system

Currently we reuse VM build system.
TODO - document platform defines and macros.

5. APR issues