diff --git a/README.adoc b/README.adoc index 13720fe77..dff889ac7 100644 --- a/README.adoc +++ b/README.adoc @@ -31,9 +31,7 @@ Process and thread IDs are available, while `getCpu()` returns `-1`. === Changes -* V3.2.0 - Add support for text configuration -* V3.1.1 - Upgraded JNA dependency to 4.4.0 -* V2.0.1 - Added getThreadId for the process if of the thread. +For detailed release notes and upgrade impact for tagged releases since the start of 2020, see link:RELEASE_NOTES.adoc[RELEASE_NOTES.adoc]. === Dependencies @@ -86,9 +84,9 @@ Note: the CPU 0 is reserved for the Operating System, it has to run somewhere. === References -https://github.com/peter-lawrey/Java-Thread-Affinity/wiki/Getting-started +https://github.com/OepnHFT/Java-Thread-Affinity/wiki/Getting-started -https://github.com/peter-lawrey/Java-Thread-Affinity/wiki/How-it-works +https://github.com/OpenHFT/Java-Thread-Affinity/wiki/How-it-works https://vanillajava.blogspot.com/2013/07/micro-jitter-busy-waiting-and-binding.html @@ -320,7 +318,7 @@ For an article on how much difference affinity can make and how to use it http:/ === Question: How to lock a specific cpuId I am currently working on a project related to deadlock detection in multithreaded programs in java. -We are trying to run threads on different processors and thus came across your github posts regarding the same. https://github.com/peter-lawrey/Java-Thread-Affinity/wiki/Getting-started +We are trying to run threads on different processors and thus came across your github posts regarding the same. https://github.com/OpenHFT/Java-Thread-Affinity/wiki/Getting-started Being a beginner, I have little knowledge and thus need your assistance. We need to know how to run threads on specified cpu number and then switch threads when one is waiting. diff --git a/RELEASE_NOTES.adoc b/RELEASE_NOTES.adoc new file mode 100644 index 000000000..8c801072b --- /dev/null +++ b/RELEASE_NOTES.adoc @@ -0,0 +1,248 @@ += Release Notes +Chronicle Software +:toc: +:sectnums: +:lang: en-GB +:source-highlighter: rouge + +This document summarises tagged Java-Thread-Affinity releases from 2020-01-01 onwards, using the annotated Git tag dates and the commit history available on 2026-04-28. +Both legacy `affinity-*` tags and `Java-Thread-Affinity-*` tags are included where they fall in that window. + +The emphasis is on user-visible behaviour, compatibility, dependency alignment, and operational impact. +Early-access releases are marked with `ea` in the version name. +The type marker uses ASCII rather than emoji to stay within the repository character-set policy: + +* `[F] Functional` - API, runtime behaviour, operating-system support, diagnostics, or lock semantics changed. +* `[N] Non-functional` - release alignment, dependency alignment, build, documentation, test, or metadata changes only. + +== Upgrade highlights + +* The latest tagged release in this window is `Java-Thread-Affinity-2026.2`. +It is primarily a Maven/BOM alignment release over `2026.1`. +* There are unreleased branch updates after `Java-Thread-Affinity-2026.2`. +The main `develop`/`ea` line only contains the post-release snapshot reset; separate feature and documentation branches contain JUnit 5 migration work and documentation clean-up. +* The main functional upgrade path after `3.23.x` is the `3.26`/`3.27`/`2026.x` line. +That line improves modern Java support, CPU id validation, hyper-thread sibling handling for `acquireCore()`, diagnostics, and test coverage. +* `AffinitySupport` was removed after the `3.23.x` line. +Applications still importing `net.openhft.affinity.AffinitySupport` should call the corresponding methods on `net.openhft.affinity.Affinity` before upgrading to `3.26.x` or later. +* Custom `LockChecker` implementations should implement `obtainLock(int id, int id2, String metaInfo)`. +The older one-id overload was deprecated in the `3.27ea1` line so a physical core can reserve more than one logical CPU when hyper-threading is present. +* Locking behaviour became safer across the 2020-2022 releases. +Notable changes include releasing an `AffinityLock` without resetting the current thread, avoiding release of locks held by other processes, improving lock metadata under contention, handling `OverlappingFileLockException`, and handling interrupted `acquireLock()` calls. +* Platform and topology support broadened over the same period. +The releases added or improved ppc64le support, ARM 32-bit and 64-bit `rdtsc`, more-than-64-core reserved masks, offline CPU handling, unusual `/proc/cpuinfo` handling, no-affinity environments, and Windows affinity-mask failure diagnostics. +* JNA handling changed materially over this period: the project moved to newer JNA releases and later added a minimum JNA major-version check. +Users with constrained or old operating-system images should verify the bundled or installed JNA version when upgrading. +* CPU selection became more explicit and easier to diagnose. +The release history includes explicit CPU-list acquisition, descriptive core names for `MicroJitterSampler`, support for very small CPU-count systems, lower-noise warnings, and clearer invalid CPU id logging. + +== Unreleased updates since `Java-Thread-Affinity-2026.2` + +These entries are based on remote branches visible on 2026-04-28. +They are not published release artefacts and may change before the next tag. + +[cols="1,3,5,5",options="header"] +|=== +|Date |Ref |Main change |Benefit / impact + +|2026-04-18 +|[N] Non-functional +`origin/sausage/docs-*` +|Documentation-only branch set covering branch-reference updates, broken URL replacement, HTTPS link upgrades, typo fixes, UK English spelling, and copyright-year clean-up. +|Improves documentation accuracy and project consistency. No runtime or API impact. + +|2026-03-30 +|[N] Non-functional +`origin/feature/junit5` +|Migrates tests to JUnit 5, makes Pax Exam migration status explicit, and adjusts temporary-directory cleanup for Windows JNA DLL locking during tests. +|Modernises the test suite and improves cross-platform test reliability. No library runtime behaviour change was identified. + +|2026-01-28 +|[N] Non-functional +`origin/develop`, `origin/ea` +|Post-release Maven state reset after `Java-Thread-Affinity-2026.2`. +|Keeps the development line ready for the next snapshot cycle. No user-facing behaviour change. +|=== + +== Release summary + +[cols="1,3,5,5",options="header"] +|=== +|Date |Release |Main change |Benefit / impact + +|2026-01-28 +|[N] Non-functional +`Java-Thread-Affinity-2026.2` +|Aligned Maven versions to Chronicle BOM `2026.2`; POM-only change from `2026.1`. +|Use when aligning with the Chronicle `2026.2` dependency stack. No user-facing behaviour change is expected from `2026.1`. + +|2026-01-28 +|[N] Non-functional +`Java-Thread-Affinity-2026.1` +|Aligned Maven versions to Chronicle BOM `2026.1` after the `2026.0` release. +|Provides release-train consistency for users consuming the Chronicle `2026.1` stack. The diff from `2026.0` is POM-only. + +|2026-01-28 +|[F] Functional +`Java-Thread-Affinity-2026.0` +|Moved to calendar versioning and `java-parent-pom` `2026.0`; carried forward the `3.27ea1` functional changes and added quality-profile, JaCoCo, dependency smoke-test, licence/header, and documentation clean-up. +|Establishes the 2026 baseline for users moving from the latest stable `3.26` line. Users get the modern Java, CPU validation, and hyper-threaded core fixes plus cleaner build governance. + +|2025-07-23 +|[N] Non-functional +`Java-Thread-Affinity-3.26.9` +|Stable `3.26` maintenance release with parent/BOM version updates only. +|Low-risk update for users staying on the `3.26` stable line and wanting dependency alignment without behaviour changes. + +|2025-07-09 +|[F] Functional +`Java-Thread-Affinity-3.27ea1` +|Fixed Java 9+ support paths, improved `AffinityLock` CPU id validation and logging, updated `acquireCore()` to lock and release all logical CPUs for a hyper-threaded core, deprecated the one-id `LockChecker.obtainLock` path, expanded tests, and refreshed README/requirements documentation. +|Improves correctness on modern JDKs and hyper-threaded hosts. Invalid CPU ids fail earlier, diagnostics are clearer, and custom `LockChecker` implementations may need a small source update. + +|2024-11-15 +|[N] Non-functional +`Java-Thread-Affinity-3.27ea0` +|Started the `3.27` early-access train and aligned parent/third-party BOM versions. +|Useful for consumers testing the next release train. No major functional change over the contemporary `3.26` stable release was identified. + +|2024-11-15 +|[N] Non-functional +`Java-Thread-Affinity-3.26.8` +|Promoted the `3.26` line to a stable release after the early-access train and aligned to release POM versions. +|Stable entry point for the `3.26` changes: modern-JDK compatibility, dependency validation, native-build scoping, and the deprecated API removal first introduced in the EA line. + +|2024-10-14 +|[F] Functional +`Java-Thread-Affinity-3.26ea6` +|Fixed a null-pointer issue and moved to a later `2.26ea` BOM. +|Improves reliability for users testing the `3.26` early-access line. + +|2024-07-19 +|[F] Functional +`Java-Thread-Affinity-3.26ea5` +|Added `rdtsc` support for ARM 64-bit and 32-bit, and made retry-after-lock-file-failure logging informational. +|Improves timing support on ARM hosts and reduces unnecessary warning noise during recoverable lock acquisition retries. + +|2024-06-15 +|[F] Functional +`Java-Thread-Affinity-3.26ea4` +|First successful `3.26` early-access release after release-train version alignment; included parent POM updates, compiler warning clean-up, Java 21 test adjustments, JNA minimum-version checking, Linux-only native build activation, and removal of the long-deprecated `AffinitySupport` compatibility class. +|Opened the `3.26` line for validation on newer build tooling and JDKs. Applications still using `AffinitySupport` need to migrate to `Affinity`. + +|2023-01-11 +|[N] Non-functional +`Java-Thread-Affinity-3.23.3` +|Updated to later `2.23` dependency versions and fixed build references to unavailable stable artefacts. +|Restores a cleaner build/dependency resolution path for `3.23` users. + +|2022-09-29 +|[N] Non-functional +`Java-Thread-Affinity-3.23.2` +|Stabilised the `3.23` line by de-snapshotting the third-party BOM and switching to stable `2.23` versions. +|Provides a stable dependency baseline for users not taking early-access builds. + +|2022-09-07 +|[F] Functional +`Java-Thread-Affinity-3.23ea1` +|Delayed a warning until an affinity lock is actually used and updated Maven execution tooling. +|Reduces startup noise for applications that include the library but do not immediately bind threads. + +|2022-08-08 +|[F] Functional +`Java-Thread-Affinity-3.23ea0` +|Handled `ClosedByInterruptException` when `acquireLock()` is interrupted, and changed too-high CPU id handling from an exception to a warning. +|Makes interrupted lock acquisition cleaner and avoids abrupt failure when a CPU id cannot be honoured on the current host. + +|2022-01-31 +|[F] Functional +`Java-Thread-Affinity-3.21ea83` +|Added descriptive core-name support for `MicroJitterSampler`, supported oligocore agents, and aligned to a newer `2.22ea` BOM. +|Improves targeted jitter sampling and operation on systems with very small CPU counts. + +|2021-11-03 +|[F] Functional +`Java-Thread-Affinity-3.21ea82` +|Handled `OverlappingFileLockException`, restored executable permissions on the native Makefile, and moved test process launching to `chronicle-test-framework`. +|Improves multi-process lock robustness and keeps build/test infrastructure aligned with Chronicle tooling. + +|2021-10-28 +|[F] Functional +`Java-Thread-Affinity-3.21ea81` +|Reworked file-lock metadata handling and multi-process affinity tests around a reproduced lock-handling issue. +|Improves correctness when processes contend for lock metadata and makes failures easier to diagnose. + +|2021-10-18 +|[F] Functional +`Java-Thread-Affinity-3.21ea80` +|Fixed `getMetaInfo` when another process holds the lock, improved multi-process test logging, and disabled unsuitable tests on non-Linux builds. +|Improves lock metadata reliability under contention and reduces cross-platform test noise. + +|2021-06-22 +|[F] Functional +`Java-Thread-Affinity-3.21ea5` +|Updated to JNA `5.8.0`, cleaned up deprecation state, and made the native Makefile optional for easier Windows builds. +|Improves native-library compatibility and reduces friction when building on Windows. + +|2021-06-17 +|[F] Functional +`Java-Thread-Affinity-3.21ea4` +|Allowed for disabled CPUs, warned when Windows `SetThreadAffinityMask` silently failed, retained the previous affinity mask on that failure, and fixed `AffinityThreadFactory` so every created thread is bound. +|Improves correctness on hosts with offline CPUs, makes Windows failures visible, and fixes a thread-factory binding bug. + +|2021-06-16 +|[N] Non-functional +`Java-Thread-Affinity-3.21ea3` +|Release-train/BOM update after `3.21ea2`. +|Dependency alignment release; no substantial user-facing source change was identified. + +|2021-05-27 +|[N] Non-functional +`Java-Thread-Affinity-3.21ea2` +|Republished the Java 12+ compatibility work under the `Java-Thread-Affinity-*` tag naming and moved to a later `2.21ea` BOM. +|Use this rather than `affinity-3.21ea1.1` when following the newer project tag naming. + +|2021-05-26 +|[F] Functional +`affinity-3.21ea1.1` +|Removed custom `java.lang` classes and `NonForkingAffinityLock`, improved lock-file deletion logging, and moved README imagery under `docs/images`. +|Makes the library behave better with Java versions that enforce module boundaries, especially Java 12 and later. + +|2021-02-22 +|[N] Non-functional +`Java-Thread-Affinity-3.21ea1` +|Updated early-access BOM versions, normalised line endings, and restored native Makefile execute permissions in Git. +|Build and packaging clean-up for the `3.21ea` line; no user-facing runtime behaviour change was identified. + +|2021-01-13 +|[F] Functional +`Java-Thread-Affinity-3.21ea0` +|Started the `3.21` early-access line; added ppc64le support, allowed `-Daffinity.reserved` masks beyond 64 cores, and added an `AffinityLock.acquireLock` path that can choose from an explicit CPU list. +|Improves operation on large-core-count and ppc64le systems, and gives callers tighter control over CPU selection. + +|2020-09-16 +|[F] Functional +`affinity-3.20.0` +|Started the `3.20` release-train naming while carrying the lock-release change that allows `AffinityLock` release without resetting the current thread. +|Useful for consumers following the `3.20` train; preserves the same lock-release benefit published as `3.2.4`. + +|2020-09-16 +|[F] Functional +`affinity-3.2.4` +|Allowed `AffinityLock` to be released without resetting the current thread, avoided releasing affinity when it had not been narrowed, and fixed `FileLockBasedLockChecker` so it does not release locks held by other processes. +|Reduces accidental affinity changes and improves multi-process lock safety. + +|2020-04-17 +|[F] Functional +`Java-Thread-Affinity-3.2.3` +|Handled no-affinity environments more gracefully and continued when `/proc/cpuinfo` is unusual, such as in some LXC or virtualised environments. +|Improves startup resilience on containers and virtual machines where CPU topology data is incomplete or non-standard. +|=== + +== Notes for maintainers + +The release history contains several release-train commits whose only effective change is Maven version alignment. +Those releases are still listed because they are published artefacts, but their impact is intentionally described as dependency or build alignment rather than runtime behaviour. + +When preparing future release notes, prefer summarising user impact rather than copying raw commit subjects. +The most useful recurring categories are API compatibility, supported Java versions, supported operating systems, lock-file behaviour, dependency/BOM alignment, and diagnostics.