diff --git a/ChangeLog b/ChangeLog index 6b709859..d2d4bfed 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +Fri Oct 13 12:21:48 CEST 2000 Daniel Veillard + + * doc/xml.html doc/xmlmem.html: added a module describing memory + interfaces and use, updated the main page. + Fri Oct 13 01:23:48 CEST 2000 Daniel Veillard * nanoftp.c nanohttp.c xmlIO.c: Wayne Davison Win32 patch diff --git a/config.h.in b/config.h.in index 5a956408..20e40dea 100644 --- a/config.h.in +++ b/config.h.in @@ -14,6 +14,7 @@ #undef HAVE_ISNAN #undef HAVE_LIBHISTORY #undef HAVE_LIBREADLINE +#undef SOCKLEN_T /* Define if you have the class function. */ #undef HAVE_CLASS @@ -153,5 +154,3 @@ /* Define if compiler has function prototypes */ #undef PROTOTYPES -/* Type of socket length (socklen_t) */ -#undef SOCKLEN_T diff --git a/doc/xml.html b/doc/xml.html index 60a66b65..19d82f11 100644 --- a/doc/xml.html +++ b/doc/xml.html @@ -3,7 +3,7 @@ The XML C library for Gnome - + @@ -53,6 +53,7 @@ alt="W3C Logo">

libxml2
  • libxml Internationalization support
  • libxml Input/Output interfaces
    • +
  • libxml Memory interfaces

    • Introduction

    @@ -65,23 +66,29 @@ structured documents/data.

    Here are some key points about libxml:

    Documentation

    @@ -125,8 +132,9 @@ structured documents/data.

    Well, bugs or missing features are always possible, and I will make a point of fixing them in a timely fashion. The best way to report a bug is to use the Gnome bug tracking -database. I look at reports there regularly and it's good to have a -reminder when a bug is still open. Check the (make sure to use the "gnome-xml" module name, not libxml or +libxml2). I look at reports there regularly and it's good to have a reminder +when a bug is still open. Check the instructions on reporting bugs and be sure to specify that the bug is for the package gnome-xml.

    @@ -160,6 +168,9 @@ href="http://bugs.gnome.org/db/pa/lgnome-xml.html">Gnome bug database::

    1. provide patches when you find problems
      2. +
    2. provide the diffs when you port libxml to a new platform. They may not + be integrated in all cases but help pinpointing portability problems and +
    3. provice documentation fixes (either as patches to the code comments or as HTML diffs).
    4. provide new documentations pieces (translations, examples, etc ...)
      5. @@ -219,10 +230,30 @@ platform, get in touch with me to upload the package. I will keep them in the

      CVS only : check the Changelog file -for really accurate description

      +for a really accurate description
        -
      • working on HTML and XML links recognition layers, get in touch with me - if you want to test those.
        • +
      • XPointer implementation and testsuite
        • +
      • Lot of XPath fixes, added variable and functions registration, more + tests
        • +
      • Portability fixes, lots of enhancements toward an easy Windows build and + release
        • +
      • Late validation fixes
        • +
      • Integrated a lot of contributed patches
        • +
      • added memory management docs
        • +
      + +

      Item floating around but not actively worked on, get in touch with me if +you want to test those

      +
        +
      • working on HTML and XML links recognition layers
        • +
      • parsing/import of Docbook SGML docs
        • +
      + +

      2.2.4: Oct 1 2000:

      +
        +
      • main XPath problem fixed
        • +
      • Integrated portability patches for Windows
        • +
      • Serious bug fixes on the URI and HTML code

      2.2.3: Sep 17 2000

      @@ -1308,6 +1339,6 @@ Gnome CVS base under gnome-xml/example

      Daniel Veillard

      -

      $Id: xml.html,v 1.52 2000/09/17 16:38:14 veillard Exp $

      +

      $Id: xml.html,v 1.53 2000/09/29 02:42:04 veillard Exp $

      diff --git a/doc/xmlmem.html b/doc/xmlmem.html new file mode 100644 index 00000000..2508a964 --- /dev/null +++ b/doc/xmlmem.html @@ -0,0 +1,160 @@ + + + + Libxml memory management + + + + + +

      Libxml memory management

      + +

      Location: http://xmlsoft.org/xmlmem.html

      + +

      Libxml home page: http://xmlsoft.org/

      + +

      Mailing-list archive: http://xmlsoft.org/messages/

      + +

      Version: $Revision$

      + +

      Table of Content:

      +
        +
      1. General overview
        2. +
      2. Setting libxml set of memory routines
        3. +
      3. Cleaning up after parsing
        4. +
      4. Debugging routines
        5. +
      5. General memory requirements
        6. +
      + +

      General overview

      + +

      The module xmlmemory.h +provides the interfaces to the libxml memory system:

      +
        +
      • libxml does not use the libc memory allocator directly but xmlFree(), + xmlMalloc() and xmlRealloc()
        • +
      • those routines can be reallocated to a specific set of routine, by + default the libc ones i.e. free(), malloc() and realloc()
        • +
      • the xmlmemory.c module includes a set of debugging routine
        • +
      + +

      Setting libxml set of memory routines

      + +

      It is sometimes useful to not use the default memory allocator, either for +debugging, analysis or to implement a specific behaviour on memory management +(like on embedded systems). Two function calls are available to do so:

      +
        +
      • xmlMemGet + () which return the current set of functions in use by the parser
        • +
      • xmlMemSetup() + which allow to set up a new set of memory allocation functions
        • +
      + +

      Of course a call to xmlMemSetup() should probably be done before calling +any other libxml routines (unless you are sure your allocations routines are +compatibles).

      + +

      Cleaning up after parsing

      + +

      Libxml is not stateless, there is a few set of memory structures needing +allocation before the parser is fully functionnal (some encoding structures +for example). This also mean that once parsing is finished there is a tiny +amount of memory (a few hundred bytes) which can be recollected if you don't +reuse the parser immediately:

      +
        +
      • xmlCleanupParser + () is a centralized routine to free the parsing states. Note that it + won't deallocate any produced tree if any (use the xmlFreeDoc() and + related routines for this).
        • +
      • xmlInitParser + () is the dual routine allowing to preallocate the parsing state which + can be useful for example to avoid initialization reentrancy problems when + using libxml in multithreaded applications
        • +
      + +

      Generally xmlCleanupParser() is safe, if needed the state will be rebuild +at the next invocation of parser routines, but be careful of the consequences +in multithreaded applications.

      + +

      Debugging routines

      + +

      When configured using --with-mem-debug flag (off by default), libxml uses a +set of memory allocation debugging routineskeeping track of all allocated +blocks and the location in the code where the routine was called. A couple of +other debugging routines allow to dump the memory allocated infos to a file or +call a specific routine when a given block number is allocated:

      + + +

      When developping libxml memory debug is enabled, the tests programs call +xmlMemoryDump () and the "make test" regression tests will check for any +memory leak during the full regression test sequence, this helps a lot +ensuring that libxml does not leak memory and bullet proof memory allocations +use (some libc implementations are known to be far too permissive resulting in +major portability problems!).

      + +

      If the .memdump reports a leak, it displays the allocation function and +also tries to give some informations about the content and structure of the +allocated blocks left. This is sufficient in most cases to find the culprit, +but not always. Assuming the allocation problem is reproductible, it is +possible to find more easilly:

      +
        +
      1. write down the block number xxxx not allocated
        2. +
      2. export the environement variable XML_MEM_BREAKPOINT=xxxx
        3. +
      3. run the program under a debugger and set a breakpoint on + xmlMallocBreakpoint() a specific function called when this precise block + is allocated
        4. +
      4. when the breakpoint is reached you can then do a fine analysis of the + allocation an step to see the condition resulting in the missing + deallocation.
        5. +
      + +

      I used to use a commercial tool to debug libxml memory problems but after +noticing that it was not detecting memory leaks that simple mechanism was used +and proved extremely efficient until now.

      + +

      General memory requirements

      + +

      How much libxml memory require ? It's hard to tell in average it depends of +a number of things:

      +
        +
      • the parser itself should work in a fixed amout of memory, except for + information maintained about the stacks of names and entities locations. + The I/O and encoding handlers will probably account for a few KBytes. This + is true for both the XML and HTML parser (though the HTML parser need more + state).
        • +
      • If you are generating the DOM tree then memory requirements will grow + nearly lineary with the size of the data. In general for a balanced + textual document the internal memory requirement is about 4 times the size + of the UTF8 serialization of this document (exmple the XML-1.0 + recommendation is a bit more of 150KBytes and takes 650KBytes of main + memory when parsed). Validation will add a amount of memory required for + maintaining the external Dtd state which should be linear with the + complexity of the content model defined by the Dtd
        • +
      • If you don't care about the advanced features of libxml like validation, + DOM, XPath or XPointer, but really need to work fixed memory requirements, + then the SAX interface should be used.
        • +
      + +

      + +

      Daniel Veillard

      + +

      $Id$

      + +