ucw/doc/relnotes.txt

   1 Release notes
   2 =============
   3
   4 6.0 (2014-06-20)
   5 ----------------
   6
   7 Incompatible changes
   8 ~~~~~~~~~~~~~~~~~~~~
   9 * *Incompatible:* It turned out that almost all users of the <<gary:,growing array>>
  10   module push/pop individual elements. Therefore, we have removed the second
  11   argument (item count) of `GARY_PUSH` and `GARY_POP`. If you want to push/pop
  12   multiple elements at once, use `GARY_PUSH_MULTI` and `GARY_POP_MULTI`.
  13 * *Incompatible:* The interface of the <<heap:,heap>> module was cleaned up
  14   to remove non-systematic side-effects. The `HEAP_INSERT` operation is now
  15   a proper insert (previously, it was just cleanup after insertion performed
  16   by the caller), similarly `HEAP_INCREASE` and `HEAP_DECREASE`. The `HEAP_DELMIN`
  17   operation was renamed to `HEAP_DELETE_MIN`. New operations `HEAP_REPLACE` and
  18   `HEAP_REPLACE_MIN` have been added. If you need to track positions of elements
  19   in the heap, please check the notes at individual functions.
  20 * The <<conf:,configuration file parser>> has been improved:
  21 ** Multiple instances of the configuration parser are supported.
  22 ** *Incompatible:* As there may be more instances, we can no longer use
  23    global variables to control the configuration system. In particular,
  24    `cf_need_journal` and `cf_pool` variables have been replaced by
  25    functions <<conf:cf_set_journalling()>> and <<conf:cf_get_pool()>>.
  26 ** *Incompatible:* Loading of configuration files has been decoupled from
  27    the getopt wrapper, so you might need to include `conf.h` for functions
  28    which were previously declared in `getopt.h`.
  29 ** New functions have been added:
  30    <<conf:cf_open_group()>>, <<conf:cf_close_group()>>, and <<conf:cf_revert()>>.
  31 ** *Incompatible:* Dynamic configuration arrays have been re-implemented in
  32    terms of our generic <<gary:,growing arrays>>. This makes them easier to
  33    use and most of the interface has been preserved. The only exception is
  34    static allocation via the DARY_ALLOC() macro, which is no longer available.
  35 * *Incompatible:* The `UCW::CGI` Perl module has its custom error handlers
  36   (which override default Perl error handlers) split off to a separate module
  37   `UCW::CGI::ErrorHandler`.
  38
  39 New modules
  40 ~~~~~~~~~~~
  41 * <<daemon:,Daemon helpers>> have been added including a new `daemon-control`
  42   utility. The old `daemon-helper` utility has been obsoleted and it is not
  43   compiled by default.
  44 * <<signal:,Signal helpers>> for translation between signal names and numbers
  45   have been added.
  46 * The fastbuf I/O layer received a new back-end <<fastbuf:fbmulti,fb_multi>>,
  47   which concatenates several fastbuf streams to form a single virtual stream.
  48 * Added <<varint:,varint>> module for efficient UTF-8-like encoding of 64-bit
  49   integers to byte sequences.
  50 * Added <<table:,table printer>> module for configurable formatting of
  51   2-dimensional tables in both user-friendly and machine-friendly ways.
  52 * A <<opt:,parser of command-line options>> has been added, similar in spirit to
  53   our <<conf:,configuration file parser>>. The <<conf:getopt_h,getopt>> module
  54   has been obsoleted
  55 * <<alloc:,Generic allocators>> have been introduced, providing an abstract
  56   way of memory allocation. <<gary:,Growing arrays>> are now based on such
  57   allocators, which allows for example growing arrays in memory pools.
  58
  59 Cleanups
  60 ~~~~~~~~
  61 * Libucw finally has a clean ABI, which does not pollute namespace, risking
  62   collisions with other libraries. However, we did not want to abandon our
  63   nicely and simply named functions, so the header files define macros,
  64   which translate names of all externally visible symbols to start with `ucw_`.
  65   If you don't like this, configure libucw with `CONFIG_UCW_CLEAN_ABI` turned off.
  66 * All helper utilities are now installed with names starting with `ucw-` to
  67   prevent collisions.
  68 * The auxiliary libraries have been renamed to `libucw-charset`, `libucw-images`,
  69   `libucw-xml`. The clean ABI promise does not extend to them yet.
  70 * The alias `uns` for `unsigned int` has been replaced by a more common `uint`.
  71   The old name is still maintained for backward compatibility.
  72 * Several functions now accept `size_t` instead of `unsigned int` for size arguments.
  73
  74 Minor changes
  75 ~~~~~~~~~~~~~
  76 * `<stdbool.h>` is automatically included by `<ucw/lib.h>`.
  77
  78 5.0 (2012-02-21)
  79 ----------------
  80
  81 * *Incompatible:* The `timestamp_t` type has been decoupled from wall clock time.
  82   It now specifies the number of milliseconds from an unspecified origin, so that
  83   it can for example refer to the system monotonic clock. The `ucw_time_t` type
  84   has been removed.
  85
  86 * The <<mainloop:,mainloop>> module has been rewritten:
  87 ** Multiple instances of the main loop are supported (to be used in different
  88    threads or locally within a library function).
  89 ** The new implementation is more efficient: it uses heaps for timers,
  90    epoll() for file descriptors (when available).
  91 ** The return value of <<mainloop:struct_main_file,`main_file`>> handlers has been
  92    changed to <<mainloop:enum_main_hook_return,`HOOK_IDLE`>> and <<mainloop:enum_main_hook_return,`HOOK_RETRY`>>.
  93    However, the numerical values are equal, so old code should keep working.
  94 ** *Incompatible:* The main loop time (`main_now`) has been decoupled from wall clock time
  95    and moved to a field in the `main_context` structure. It can be accessed either directly
  96    or via <<mainloop:main_get_now()>>. The `main_now_seconds` variable has
  97    been removed, `main_idle_time` has become a structure field.
  98 ** *Incompatible:* The interface for asynchronous reading and writing
  99    (file_read() and friends) has been separated from the core of the main loop.
 100    Use <<mainloop:struct_main_block_io,`struct main_block_io`>> and related functions instead.
 101 ** *Incompatible:* file_close_all() is gone. You have to call <<mainloop:main_teardown()>>
 102    or <<mainloop:main_destroy()>> to clean up properly after fork().
 103 ** Added support for <<mainloop:signal,synchronous delivery of signals>>.
 104 ** Added relative timers: <<mainloop:timer_add_rel()>>.
 105 ** Modification of events from a running event handler is always safe.
 106 ** Deleting an already deleted event is always safe.
 107 ** For any event type, it is possible to ask whether it is active (added to the mainloop) or not: <<mainloop:hook_is_active()>> and friends.
 108 ** A new mainloop front-end for asynchronous <<mainloop:recordio,record-based I/O>> has been added.
 109
 110 * Added support for <<trans:,resource pools and transactions>>, which is a general
 111   mechanism for tracking resources and reporting errors. It is still considered
 112   experimental, so the API can change in future releases.
 113
 114 * Added a <<gary:,growing array>> module `gary.h`, similar to `gbuf.h`, but with
 115   a much more convenient interface.
 116
 117 * The <<lists:,Circular linked lists>> can recognize unlinked nodes,
 118   see <<lists:clist_unlink()>>.
 119
 120 * Added `strtonum.h` -- a module for precise parsing of numbers.
 121
 122 * When compiled by a recent enough GCC, `__thread` is used for thread-local variables,
 123   which is more efficient than the POSIX per-thread storage.
 124 ** *Incompatible:* `ucwlib_context->thread_id` is no longer available directly,
 125   please use <<thread:ucwlib_thread_id()>> instead.
 126
 127 * *Incompatible:* Several modules have been declared obsolete and removed:
 128 ** `sighandler` -- generic signal handling (it still exists internally)
 129 ** `qache` -- a mmap-based shared cache
 130 ** `prefetch` -- an interface to memory prefetch instructions; superseded by GCC `__builtin_prefetch`
 131 ** `randomkey` -- a generator of cryptographically strong pseudo-random tokens; will be replaced
 132    by something more generic soon
 133 ** `profile` -- a profiling hack
 134
 135 * *Incompatible:* Several modules now have their own header files:
 136 ** `process.h` -- all functions related to processes, previously declared in `lib.h`
 137 ** `io.h` -- functions related to files from `lib.h` and `lfs.h`
 138 ** `time.h` -- timestamps and interval timers, previously in `lib.h`
 139
 140 * *Incompatible:* Several configuration options were renamed or removed:
 141 ** `CONFIG_FAKE_ELTPOOL` &rarr; `CONFIG_UCW_FAKE_ELTPOOL`
 142 ** `CONFIG_LARGE_FILES` &rarr; `CONFIG_UCW_LARGE_FILES`
 143 ** `CONFIG_OWN_GETOPT` &rarr; `CONFIG_UCW_OWN_GETOPT`
 144 ** `CONFIG_DIRECT_IO` &rarr; `CONFIG_UCW_DIRECT_IO`
 145 ** `DEFAULT_CONFIG` &rarr; `CONFIG_UCW_DEFAULT_CONFIG`
 146 ** `ENV_VAR_CONFIG` &rarr; `CONFIG_UCW_ENV_VAR_CONFIG`
 147 ** `CONFIG_LFS` was removed
 148 ** `CONFIG_URL_ESCAPE_COMPAT` was removed
 149
 150 * `UCW::Configure` supports running of test programs.
 151
 152 * `UCW::CGI` support multiple argument tables and UTF-8 mode. Also, it uses the
 153   proper HTTP status codes when reporting errors.
 154
 155 * Implementation details of <<fastbuf:,fastbufs>> have changed. The new code checks
 156   invariants more carefully, so it is possible that custom fastbuf back-ends which
 157   are buggy now fail, although they previously seemed to work.
 158
 159
 160 4.0 (2009-04-13)
 161 ----------------
 162 This was the first stand-alone release of LibUCW. Before that, LibUCW was developed
 163 as a part of the http://www.ucw.cz/holmes/[Sherlock Holmes project].