From d5def2d42bfb6edda8bb054e2729e3e3a63bcd09 Mon Sep 17 00:00:00 2001 From: Iwan Kelaiah Date: Fri, 12 Jun 2026 08:48:17 +1000 Subject: [PATCH 1/2] docs(release): v0.6.5 - document cthreads requirement for Linux/macOS Programs that use this library on Unix-like systems must list cthreads as the first unit in their uses clause, or creating the pool crashes at runtime with an access violation (exit code 217) - a runtime failure, not a compile error. This release documents the requirement everywhere a new user looks. No code or API changes. - README: prominent cthreads note at the top of Quick Start; add the {$IFDEF UNIX}cthreads{$ENDIF} guard to every Quick Start and Installation snippet; reminder in the compilation Tip. - docs/ThreadPool.Simple-API.md, docs/ThreadPool.ProducerConsumer-API.md: add a platform note at the top of each. - docs/release-notes-v0.6.5.md: new release note. - README "Planned/In Progress": drop adaptive thread adjustment (conflicts with the fixed-count design); add richer error handling, planned for 0.7.0. - Bump version to 0.6.5 (README badge, package .lpk). --- CHANGELOG.md | 11 +++++ README.md | 40 ++++++++++++++--- docs/ThreadPool.ProducerConsumer-API.md | 10 +++++ docs/ThreadPool.Simple-API.md | 10 +++++ docs/release-notes-v0.6.5.md | 57 +++++++++++++++++++++++++ package/lazarus/threadpool_fp.lpk | 2 +- 6 files changed, 123 insertions(+), 7 deletions(-) create mode 100644 docs/release-notes-v0.6.5.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 503ae42..efc09dd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,17 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). +## [0.6.5] - 2026-06-11 + +### Added + +- README: prominent `cthreads` note in Quick Start, plus the `{$IFDEF UNIX}cthreads{$ENDIF}` guard in every Quick Start and Installation snippet — programs that use this library on Linux/macOS must list `cthreads` as their first unit or they crash at runtime with an access violation (exit code 217) +- Platform note about `cthreads` at the top of both API documents (`ThreadPool.Simple-API.md`, `ThreadPool.ProducerConsumer-API.md`) + +### Changed + +- README "Planned/In Progress": dropped adaptive thread adjustment (it conflicts with the library's fixed-count, intentionally-simple design); replaced with richer error handling, planned for 0.7.0 + ## [0.6.0] - 2026-06-11 ### Added diff --git a/README.md b/README.md index fe1e8bd..d46ae3e 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # 🚀 ThreadPool for Free Pascal -[![Version](https://img.shields.io/badge/version-0.6.0-8B5CF6.svg)](CHANGELOG.md) +[![Version](https://img.shields.io/badge/version-0.6.5-8B5CF6.svg)](CHANGELOG.md) [![License: MIT](https://img.shields.io/badge/License-MIT-1E3A8A.svg)](https://opensource.org/licenses/MIT) [![Free Pascal](https://img.shields.io/badge/Free%20Pascal-3.2.2+-3B82F6.svg)](https://www.freepascal.org/) [![Lazarus](https://img.shields.io/badge/Lazarus-4.0+-60A5FA.svg)](https://www.lazarus-ide.org/) @@ -133,9 +133,28 @@ A thread pool with fixed-size circular buffer (1024 items) and built-in backpres ## 🏃 Quick Start +> [!IMPORTANT] +> **On Linux/macOS, your program must use the `cthreads` unit — and it must be the *first* unit in your program's `uses` clause.** +> +> Free Pascal does not install a threading manager by default on Unix-like systems. Without `cthreads`, creating the thread pool fails at runtime with an access violation (exit code 217). Windows does not need it. +> +> ```pascal +> program MyApp; +> {$mode objfpc}{$H+} +> uses +> {$IFDEF UNIX} +> cthreads, // MUST be first on Linux/macOS +> {$ENDIF} +> ThreadPool.Simple; // or ThreadPool.ProducerConsumer +> ``` +> +> The examples in this repository already include this guard — see `examples/Starter/Starter.lpr`. + ### Simple Thread Pool ```pascal -uses ThreadPool.Simple; +uses + {$IFDEF UNIX}cthreads,{$ENDIF} // see the note above — required on Linux/macOS + ThreadPool.Simple; // Simple parallel processing procedure ProcessItem(index: Integer); @@ -154,7 +173,9 @@ end; ### Producer-Consumer Thread Pool ```pascal -uses ThreadPool.ProducerConsumer; +uses + {$IFDEF UNIX}cthreads,{$ENDIF} // see the note above — required on Linux/macOS + ThreadPool.ProducerConsumer; procedure DoWork; begin @@ -361,12 +382,16 @@ All four `Queue` overloads share the same pattern — pick the one that fits you For Simple Thread Pool: ```pascal - uses ThreadPool.Simple; + uses + {$IFDEF UNIX}cthreads,{$ENDIF} // required on Linux/macOS (must be first) + ThreadPool.Simple; ``` For Producer-Consumer Thread Pool: ```pascal - uses ThreadPool.ProducerConsumer; + uses + {$IFDEF UNIX}cthreads,{$ENDIF} // required on Linux/macOS (must be first) + ThreadPool.ProducerConsumer; ``` 3. Start using: @@ -406,6 +431,8 @@ All tasks completed successfully! > [!TIP] > Make sure your source file starts with `{$mode objfpc}{$H+}`. Without this, Free Pascal defaults to TP/Delphi-7 mode and some syntax will not compile. +> +> On Linux/macOS, also ensure `{$IFDEF UNIX}cthreads{$ENDIF}` is the **first** unit in your program's `uses` clause (see the [Quick Start](#-quick-start) note). Forgetting it causes a runtime access violation, not a compile error — so the build succeeds but the program crashes when it creates the pool. ## ⚙️ Requirements @@ -517,7 +544,8 @@ GlobalThreadPool.WaitForAll; ``` ## 🚧 Planned/In Progress -- Adaptive thread adjustment based on a load factor + +- Richer error handling — collect all task errors (not just the last) and an optional `OnError` callback (planned for 0.7.0) - Support for `procedure Queue(AMethod: TProc; AArgs: array of Const);` - More comprehensive tests - More examples diff --git a/docs/ThreadPool.ProducerConsumer-API.md b/docs/ThreadPool.ProducerConsumer-API.md index 04b3a4d..5cd4edb 100644 --- a/docs/ThreadPool.ProducerConsumer-API.md +++ b/docs/ThreadPool.ProducerConsumer-API.md @@ -8,6 +8,16 @@ outpace consumption and you need predictable memory usage and overflow control. For simpler use cases see `ThreadPool.Simple`. +> **Linux/macOS:** your program must list `cthreads` as the **first** unit in its +> `uses` clause, or creating the pool will raise a runtime access violation +> (exit code 217). Windows does not need it. +> +> ```pascal +> uses +> {$IFDEF UNIX}cthreads,{$ENDIF} // must be first on Unix-like systems +> ThreadPool.ProducerConsumer; +> ``` + --- ## Constructor diff --git a/docs/ThreadPool.Simple-API.md b/docs/ThreadPool.Simple-API.md index b01dd81..22a1657 100644 --- a/docs/ThreadPool.Simple-API.md +++ b/docs/ThreadPool.Simple-API.md @@ -1,5 +1,15 @@ # ThreadPool.Simple API Documentation +> **Linux/macOS:** your program must list `cthreads` as the **first** unit in its +> `uses` clause, or creating the pool will raise a runtime access violation +> (exit code 217). Windows does not need it. +> +> ```pascal +> uses +> {$IFDEF UNIX}cthreads,{$ENDIF} // must be first on Unix-like systems +> ThreadPool.Simple; +> ``` + ## Thread Pool Types ### GlobalThreadPool diff --git a/docs/release-notes-v0.6.5.md b/docs/release-notes-v0.6.5.md new file mode 100644 index 0000000..eaf768e --- /dev/null +++ b/docs/release-notes-v0.6.5.md @@ -0,0 +1,57 @@ +# ThreadPool for Free Pascal — v0.6.5 + +A small, documentation-focused release. **There are no code or API changes** — +existing programs compile and run exactly as before. The goal is to stop new +Linux/macOS users from hitting a confusing runtime crash. + +## Why this release exists + +On Unix-like systems (Linux, macOS), Free Pascal does **not** install a +threading manager by default. Any program that creates threads must include the +`cthreads` unit as the **first** unit in its `uses` clause. Without it, creating +the thread pool fails at runtime with an access violation (exit code 217) — +**not** a compile error, so the build succeeds and the crash only appears when +the program runs. + +This caught us during CI setup, and it will catch anyone building their own +program against this library. v0.6.5 documents the requirement everywhere a new +user is likely to look. + +```pascal +program MyApp; +{$mode objfpc}{$H+} +uses + {$IFDEF UNIX} + cthreads, // MUST be first on Linux/macOS + {$ENDIF} + ThreadPool.Simple; // or ThreadPool.ProducerConsumer +``` + +Windows does not need `cthreads` and is unaffected. + +## What changed + +- **README** — a prominent note at the top of Quick Start explaining the + `cthreads` requirement, plus the `{$IFDEF UNIX}cthreads{$ENDIF}` guard added + to every Quick Start and Installation snippet, and a reminder in the + compilation Tip. +- **API docs** — a platform note at the top of both + `ThreadPool.Simple-API.md` and `ThreadPool.ProducerConsumer-API.md`. +- **Roadmap** — "Planned/In Progress" dropped adaptive thread adjustment (it + conflicts with the library's intentionally simple, fixed-count design) and + added richer error handling, planned for 0.7.0. + +> The examples in this repository already include the `cthreads` guard (added in +> v0.6.0), so they build and run correctly on both platforms — see +> `examples/Starter/Starter.lpr`. + +## Upgrade notes + +- **Nothing to change in your code.** If your program already runs correctly on + Linux/macOS, it already has `cthreads` and is fine. +- If you are *new* to the library on Linux/macOS, add the `cthreads` guard shown + above as the first unit in your program. + +## Full changelog + +See [CHANGELOG.md](../CHANGELOG.md) for the complete version history. diff --git a/package/lazarus/threadpool_fp.lpk b/package/lazarus/threadpool_fp.lpk index 247293c..5c31584 100644 --- a/package/lazarus/threadpool_fp.lpk +++ b/package/lazarus/threadpool_fp.lpk @@ -81,7 +81,7 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. "/> - + From 80294259f216fa66bd9694b0cbadc93c90dba884 Mon Sep 17 00:00:00 2001 From: Iwan Kelaiah Date: Fri, 12 Jun 2026 17:40:26 +1000 Subject: [PATCH 2/2] feat(doc): include a ref from the official site - cthreads --- README.md | 2 ++ docs/ThreadPool.ProducerConsumer-API.md | 2 ++ docs/ThreadPool.Simple-API.md | 2 ++ 3 files changed, 6 insertions(+) diff --git a/README.md b/README.md index d46ae3e..478997a 100644 --- a/README.md +++ b/README.md @@ -149,6 +149,8 @@ A thread pool with fixed-size circular buffer (1024 items) and built-in backpres > ``` > > The examples in this repository already include this guard — see `examples/Starter/Starter.lpr`. +> +> From the [official FPC documentation](https://www.freepascal.org/docs-html/rtl/cthreads/index.html): *"The cthreads unit simply needs to be included in the uses clause of the program, preferably the very first unit, and the initialization section of the unit will do all the work."* ### Simple Thread Pool ```pascal diff --git a/docs/ThreadPool.ProducerConsumer-API.md b/docs/ThreadPool.ProducerConsumer-API.md index 5cd4edb..05e7265 100644 --- a/docs/ThreadPool.ProducerConsumer-API.md +++ b/docs/ThreadPool.ProducerConsumer-API.md @@ -17,6 +17,8 @@ For simpler use cases see `ThreadPool.Simple`. > {$IFDEF UNIX}cthreads,{$ENDIF} // must be first on Unix-like systems > ThreadPool.ProducerConsumer; > ``` +> +> See the [official FPC documentation on `cthreads`](https://www.freepascal.org/docs-html/rtl/cthreads/index.html). --- diff --git a/docs/ThreadPool.Simple-API.md b/docs/ThreadPool.Simple-API.md index 22a1657..3fd5604 100644 --- a/docs/ThreadPool.Simple-API.md +++ b/docs/ThreadPool.Simple-API.md @@ -9,6 +9,8 @@ > {$IFDEF UNIX}cthreads,{$ENDIF} // must be first on Unix-like systems > ThreadPool.Simple; > ``` +> +> See the [official FPC documentation on `cthreads`](https://www.freepascal.org/docs-html/rtl/cthreads/index.html). ## Thread Pool Types