112 lines
4.9 KiB
Markdown
112 lines
4.9 KiB
Markdown
|
Porting applications to use zlib-ng
|
|||
|
|
===================================
|
|||
|
|
|
|||
|
|
Zlib-ng can be used/compiled in two different modes, that require some
|
|||
|
|
consideration by the application developer.
|
|||
|
|
|
|||
|
|
Changes from zlib affecting native and compat modes
|
|||
|
|
---------------------------------------------------
|
|||
|
|
Zlib-ng is not as conservative with memory allocation as Zlib is.
|
|||
|
|
|
|||
|
|
Where Zlib's inflate will allocate a lower amount of memory depending on
|
|||
|
|
compression level and window size, zlib-ng will always allocate the maximum
|
|||
|
|
amount of memory and possibly leave parts of it unused.
|
|||
|
|
Zlib-ng's deflate will however allocate a lower amount of memory depending
|
|||
|
|
on compression level and window size.
|
|||
|
|
|
|||
|
|
Zlib-ng also allocates one "big" buffer instead of doing multiple smaller
|
|||
|
|
allocations. This is faster, can lead to better cache locality and reduces
|
|||
|
|
space lost to alignment padding.
|
|||
|
|
|
|||
|
|
At the time of writing, by default zlib-ng allocates the following amounts
|
|||
|
|
of memory on a 64-bit system (except on S390x that requires ~4KiB more):
|
|||
|
|
- Deflate: 350.272 Bytes
|
|||
|
|
- Inflate: 42.112 Bytes
|
|||
|
|
|
|||
|
|
**Advantages:**
|
|||
|
|
- All memory is allocated during DeflateInit or InflateInit functions,
|
|||
|
|
leaving the actual deflate/inflate functions free from allocations.
|
|||
|
|
- Zlib-ng can only fail from memory allocation errors during init.
|
|||
|
|
- Time spent doing memory allocation systemcalls is all done during init,
|
|||
|
|
allowing applications to do prepare this before doing latency-sensitive
|
|||
|
|
deflate/inflate later.
|
|||
|
|
- Can reduce wasted memory due to buffer alignment padding both by OS and zlib-ng.
|
|||
|
|
- Potentially improved memory locality.
|
|||
|
|
|
|||
|
|
**Disadvantages:**
|
|||
|
|
- Zlib-ng allocates a little more memory than zlib does.
|
|||
|
|
|
|||
|
|
zlib-compat mode
|
|||
|
|
----------------
|
|||
|
|
Zlib-ng can be compiled in zlib-compat mode, suitable for zlib-replacement
|
|||
|
|
in a single application or system-wide.
|
|||
|
|
|
|||
|
|
Please note that zlib-ng in zlib-compat mode tries to maintain both API and
|
|||
|
|
ABI compatibility with the original zlib. Any issues regarding compatibility
|
|||
|
|
can be reported as bugs.
|
|||
|
|
|
|||
|
|
In certain instances you may not be able to simply replace the zlib library/dll
|
|||
|
|
files and expect the application to work. The application may need to be
|
|||
|
|
recompiled against the zlib-ng headers and libs to ensure full compatibility.
|
|||
|
|
|
|||
|
|
It is also possible for the deflate output stream to differ from the original
|
|||
|
|
zlib due to algorithmic differences between the two libraries. Any tests or
|
|||
|
|
applications that depend on the exact length of the deflate stream being a
|
|||
|
|
certain value will need to be updated.
|
|||
|
|
|
|||
|
|
**Advantages:**
|
|||
|
|
- Easy to port to, since it only requires a recompile of the application and
|
|||
|
|
no changes to the application code.
|
|||
|
|
|
|||
|
|
**Disadvantages:**
|
|||
|
|
- Can conflict with a system-installed zlib, as that can often be linked in
|
|||
|
|
by another library you are linking into your application. This can cause
|
|||
|
|
crashes or incorrect output.
|
|||
|
|
- If your application is pre-allocating a memory buffer and you are providing
|
|||
|
|
deflate/inflate init with your own allocator that allocates from that buffer
|
|||
|
|
(looking at you nginx), you should be aware that zlib-ng needs to allocate
|
|||
|
|
more memory than stock zlib needs. The same problem exists with Intel’s and
|
|||
|
|
Cloudflare’s zlib forks. Doing this is not recommended since it makes it
|
|||
|
|
very hard to maintain compatibility over time.
|
|||
|
|
|
|||
|
|
**Build Considerations:**
|
|||
|
|
- Compile against the *zlib.h* provided by zlib-ng
|
|||
|
|
- Configuration header is named *zconf.h*
|
|||
|
|
- Static library is *libz.a* on Unix and macOS, or *zlib.lib* on Windows
|
|||
|
|
- Shared library is *libz.so* on Unix, *libz.dylib* on macOS, or *zlib1.dll*
|
|||
|
|
on Windows
|
|||
|
|
- Type `z_size_t` is *unsigned __int64* on 64-bit Windows, and *unsigned long* on 32-bit Windows, Unix and macOS
|
|||
|
|
- Type `z_uintmax_t` is *unsigned long* in zlib-compat mode, and *size_t* with zlib-ng API
|
|||
|
|
|
|||
|
|
zlib-ng native mode
|
|||
|
|
-------------------
|
|||
|
|
Zlib-ng in native mode is suitable for co-existing with the standard zlib
|
|||
|
|
library, allowing applications to implement support and testing separately.
|
|||
|
|
|
|||
|
|
The zlib-ng native has implemented some modernization and simplifications
|
|||
|
|
in its API, intended to make life easier for application developers.
|
|||
|
|
|
|||
|
|
**Advantages:**
|
|||
|
|
- Does not conflict with other zlib implementations, and can co-exist as a
|
|||
|
|
system library along with zlib.
|
|||
|
|
- In certain places zlib-ng native uses more appropriate data types, removing
|
|||
|
|
the need for some workarounds in the API compared to zlib.
|
|||
|
|
|
|||
|
|
**Disadvantages:**
|
|||
|
|
- Requires minor changes to applications to use the prefixed zlib-ng
|
|||
|
|
function calls and structs. Usually this means a small prefix `zng_` has to be added.
|
|||
|
|
|
|||
|
|
**Build Considerations:**
|
|||
|
|
- Compile against *zlib-ng.h*
|
|||
|
|
- Configuration header is named *zconf-ng.h*
|
|||
|
|
- Static library is *libz-ng.a* on Unix and macOS, or *zlib-ng.lib* on Windows
|
|||
|
|
- Shared library is *libz-ng.so* on Unix, *libz-ng.dylib* on macOS, or
|
|||
|
|
*zlib-ng2.dll* on Windows
|
|||
|
|
- Type `z_size_t` is *size_t*
|
|||
|
|
|
|||
|
|
zlib-ng compile-time detection
|
|||
|
|
------------------------------
|
|||
|
|
|
|||
|
|
To distinguish zlib-ng from other zlib implementations at compile-time check for the
|
|||
|
|
existence of `ZLIBNG_VERSION` defined in the zlib header.
|