Skip to content

Integrate jlibdeflate for faster DEFLATE compression and decompression#1768

Merged
tfenne merged 3 commits intodevfrom
tf_jlibdeflate_integration
Apr 11, 2026
Merged

Integrate jlibdeflate for faster DEFLATE compression and decompression#1768
tfenne merged 3 commits intodevfrom
tf_jlibdeflate_integration

Conversation

@tfenne
Copy link
Copy Markdown
Member

@tfenne tfenne commented Apr 2, 2026

Add optional jlibdeflate (libdeflate JNI bindings) support that is automatically used when the native library is available on the classpath, with transparent fallback to the JDK Inflater/Deflater.

It should be noted that jlibdeflate (https://github.com/fulcrumgenomics/jlibdeflate) is brand new, and is developed specifically to be used here. On pure BAM roundtrip on mac/aarch64 it is more than 2x faster than the built in jdk/zlib implementation!! Once we reach consensus on this PR I'll create a first release of jlibdeflate and publish to sonatype, and amend this PR.

  • DeflaterFactory/InflaterFactory auto-detect jlibdeflate availability at first use, caching the result for the lifetime of the JVM
  • LibdeflateDeflater/LibdeflateInflater extend JDK Deflater/Inflater and correctly handle both raw DEFLATE (nowrap=true) and zlib format (nowrap=false)
  • New Defaults.USE_LIBDEFLATE (samjdk.use_libdeflate) defaults to true; set to false to force JDK-only compression
  • jlibdeflate 0.1.0-SNAPSHOT added as a dependency from Sonatype Central snapshots

Things to think about before submitting:

  • Make sure your changes compile and new tests pass locally.
  • Add new tests or update existing ones:
    • A bug fix should include a test that previously would have failed and passes now.
    • New features should come with new tests that exercise and validate the new functionality.
  • Extended the README / documentation, if necessary
  • Check your code style.
  • Write a clear commit title and message
    • The commit message should describe what changed and is targeted at htsjdk developers
    • Breaking changes should be mentioned in the commit message.

Copy link
Copy Markdown
Member

@nh13 nh13 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looking good, just a few questions and one extra C

Comment thread build.gradle Outdated

task.jvmArgs '-Djava.awt.headless=true' //this prevents awt from displaying a java icon while the tests are running

C
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

issue:

Suggested change
C

Comment thread src/main/java/htsjdk/samtools/util/zip/LibdeflateDeflater.java Outdated
Comment thread src/main/java/htsjdk/samtools/util/zip/LibdeflateDeflater.java Outdated
Comment thread build.gradle Outdated
}

dependencies {
implementation 'com.fulcrumgenomics:jlibdeflate:0.1.0-SNAPSHOT'
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

todo:
update before merge

Comment thread src/main/java/htsjdk/samtools/util/zip/LibdeflateDeflater.java
@@ -0,0 +1,121 @@
package htsjdk.samtools.util.zip;
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nitpick: all other files have licenses in their header, should we follow that same convention

}

/** Returns true if the libdeflate native library can be loaded. */
static boolean isLibdeflateAvailable() {
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nitpick: it seems odd that InflaterFactory calls a method on DeflatorFactory, but putting it into it's own separate class seems odd too. 🤷

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed. Feels like it should just be CompressionFactory, but consolidating the two would be a bigger breaking change now.

@tfenne tfenne force-pushed the tf_bam_optimization branch from 3fa0f9f to 4d694af Compare April 11, 2026 02:06
Base automatically changed from tf_bam_optimization to dev April 11, 2026 02:23
tfenne and others added 3 commits April 10, 2026 20:30
Add optional jlibdeflate (libdeflate JNI bindings) support that is automatically
used when the native library is available on the classpath, with transparent
fallback to the JDK Inflater/Deflater.

- DeflaterFactory/InflaterFactory auto-detect jlibdeflate availability at
  first use, caching the result for the lifetime of the JVM
- LibdeflateDeflater/LibdeflateInflater extend JDK Deflater/Inflater and
  correctly handle both raw DEFLATE (nowrap=true) and zlib format (nowrap=false)
- New Defaults.USE_LIBDEFLATE (samjdk.use_libdeflate) defaults to true;
  set to false to force JDK-only compression
- jlibdeflate 0.1.0-SNAPSHOT added as a dependency from Sonatype Central snapshots
Co-authored-by: Nils Homer <nh13@users.noreply.github.com>
@tfenne tfenne force-pushed the tf_jlibdeflate_integration branch from d21cc0b to abfe4a6 Compare April 11, 2026 03:03
@tfenne tfenne merged commit df6bb84 into dev Apr 11, 2026
3 checks passed
@tfenne tfenne deleted the tf_jlibdeflate_integration branch April 11, 2026 03:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants