68b2e7f763
Some checks failed
sm-rpc / build (Debug, arm-linux-gnueabihf) (push) Successful in 1m34s
sm-rpc / build (Debug, aarch64-linux-gnu) (push) Successful in 2m46s
sm-rpc / build (Debug, host.gcc) (push) Failing after 1m28s
sm-rpc / build (Release, aarch64-linux-gnu) (push) Successful in 2m14s
sm-rpc / build (Release, arm-linux-gnueabihf) (push) Successful in 2m8s
sm-rpc / build (Debug, mipsel-linux-gnu) (push) Successful in 5m35s
sm-rpc / build (Release, host.gcc) (push) Failing after 1m55s
sm-rpc / build (Release, mipsel-linux-gnu) (push) Successful in 7m21s
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.
|