Skip to content

Commit 0f16029

Browse files
ikelaiahikelaiah
authored
Merge pull request #9 from ikelaiah/feat/v0.6.5-cthreads-docs
Feat/v0.6.5 cthreads docs
2 parents 7e6d4fe + 8029425 commit 0f16029

6 files changed

Lines changed: 129 additions & 7 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,17 @@ All notable changes to this project will be documented in this file.
44

55
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
66

7+
## [0.6.5] - 2026-06-11
8+
9+
### Added
10+
11+
- 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)
12+
- Platform note about `cthreads` at the top of both API documents (`ThreadPool.Simple-API.md`, `ThreadPool.ProducerConsumer-API.md`)
13+
14+
### Changed
15+
16+
- 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
17+
718
## [0.6.0] - 2026-06-11
819

920
### Added

‎README.md‎

Lines changed: 36 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# 🚀 ThreadPool for Free Pascal
22

3-
[![Version](https://img.shields.io/badge/version-0.6.0-8B5CF6.svg)](CHANGELOG.md)
3+
[![Version](https://img.shields.io/badge/version-0.6.5-8B5CF6.svg)](CHANGELOG.md)
44
[![License: MIT](https://img.shields.io/badge/License-MIT-1E3A8A.svg)](https://opensource.org/licenses/MIT)
55
[![Free Pascal](https://img.shields.io/badge/Free%20Pascal-3.2.2+-3B82F6.svg)](https://www.freepascal.org/)
66
[![Lazarus](https://img.shields.io/badge/Lazarus-4.0+-60A5FA.svg)](https://www.lazarus-ide.org/)
@@ -133,9 +133,30 @@ A thread pool with fixed-size circular buffer (1024 items) and built-in backpres
133133
134134
## 🏃 Quick Start
135135

136+
> [!IMPORTANT]
137+
> **On Linux/macOS, your program must use the `cthreads` unit — and it must be the *first* unit in your program's `uses` clause.**
138+
>
139+
> 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.
140+
>
141+
> ```pascal
142+
> program MyApp;
143+
> {$mode objfpc}{$H+}
144+
> uses
145+
> {$IFDEF UNIX}
146+
> cthreads, // MUST be first on Linux/macOS
147+
> {$ENDIF}
148+
> ThreadPool.Simple; // or ThreadPool.ProducerConsumer
149+
> ```
150+
>
151+
> The examples in this repository already include this guard — see `examples/Starter/Starter.lpr`.
152+
>
153+
> 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."*
154+
136155
### Simple Thread Pool
137156
```pascal
138-
uses ThreadPool.Simple;
157+
uses
158+
{$IFDEF UNIX}cthreads,{$ENDIF} // see the note above — required on Linux/macOS
159+
ThreadPool.Simple;
139160
140161
// Simple parallel processing
141162
procedure ProcessItem(index: Integer);
@@ -154,7 +175,9 @@ end;
154175
155176
### Producer-Consumer Thread Pool
156177
```pascal
157-
uses ThreadPool.ProducerConsumer;
178+
uses
179+
{$IFDEF UNIX}cthreads,{$ENDIF} // see the note above — required on Linux/macOS
180+
ThreadPool.ProducerConsumer;
158181
159182
procedure DoWork;
160183
begin
@@ -361,12 +384,16 @@ All four `Queue` overloads share the same pattern — pick the one that fits you
361384

362385
For Simple Thread Pool:
363386
```pascal
364-
uses ThreadPool.Simple;
387+
uses
388+
{$IFDEF UNIX}cthreads,{$ENDIF} // required on Linux/macOS (must be first)
389+
ThreadPool.Simple;
365390
```
366391

367392
For Producer-Consumer Thread Pool:
368393
```pascal
369-
uses ThreadPool.ProducerConsumer;
394+
uses
395+
{$IFDEF UNIX}cthreads,{$ENDIF} // required on Linux/macOS (must be first)
396+
ThreadPool.ProducerConsumer;
370397
```
371398

372399
3. Start using:
@@ -406,6 +433,8 @@ All tasks completed successfully!
406433

407434
> [!TIP]
408435
> 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.
436+
>
437+
> 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.
409438
410439
## ⚙️ Requirements
411440

@@ -517,7 +546,8 @@ GlobalThreadPool.WaitForAll;
517546
```
518547

519548
## 🚧 Planned/In Progress
520-
- Adaptive thread adjustment based on a load factor
549+
550+
- Richer error handling — collect all task errors (not just the last) and an optional `OnError` callback (planned for 0.7.0)
521551
- Support for `procedure Queue(AMethod: TProc; AArgs: array of Const);`
522552
- More comprehensive tests
523553
- More examples

‎docs/ThreadPool.ProducerConsumer-API.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,18 @@ outpace consumption and you need predictable memory usage and overflow control.
88

99
For simpler use cases see `ThreadPool.Simple`.
1010

11+
> **Linux/macOS:** your program must list `cthreads` as the **first** unit in its
12+
> `uses` clause, or creating the pool will raise a runtime access violation
13+
> (exit code 217). Windows does not need it.
14+
>
15+
> ```pascal
16+
> uses
17+
> {$IFDEF UNIX}cthreads,{$ENDIF} // must be first on Unix-like systems
18+
> ThreadPool.ProducerConsumer;
19+
> ```
20+
>
21+
> See the [official FPC documentation on `cthreads`](https://www.freepascal.org/docs-html/rtl/cthreads/index.html).
22+
1123
---
1224
1325
## Constructor

‎docs/ThreadPool.Simple-API.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,17 @@
11
# ThreadPool.Simple API Documentation
22

3+
> **Linux/macOS:** your program must list `cthreads` as the **first** unit in its
4+
> `uses` clause, or creating the pool will raise a runtime access violation
5+
> (exit code 217). Windows does not need it.
6+
>
7+
> ```pascal
8+
> uses
9+
> {$IFDEF UNIX}cthreads,{$ENDIF} // must be first on Unix-like systems
10+
> ThreadPool.Simple;
11+
> ```
12+
>
13+
> See the [official FPC documentation on `cthreads`](https://www.freepascal.org/docs-html/rtl/cthreads/index.html).
14+
315
## Thread Pool Types
416
517
### GlobalThreadPool

‎docs/release-notes-v0.6.5.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# ThreadPool for Free Pascal — v0.6.5
2+
3+
A small, documentation-focused release. **There are no code or API changes** —
4+
existing programs compile and run exactly as before. The goal is to stop new
5+
Linux/macOS users from hitting a confusing runtime crash.
6+
7+
## Why this release exists
8+
9+
On Unix-like systems (Linux, macOS), Free Pascal does **not** install a
10+
threading manager by default. Any program that creates threads must include the
11+
`cthreads` unit as the **first** unit in its `uses` clause. Without it, creating
12+
the thread pool fails at runtime with an access violation (exit code 217) —
13+
**not** a compile error, so the build succeeds and the crash only appears when
14+
the program runs.
15+
16+
This caught us during CI setup, and it will catch anyone building their own
17+
program against this library. v0.6.5 documents the requirement everywhere a new
18+
user is likely to look.
19+
20+
```pascal
21+
program MyApp;
22+
{$mode objfpc}{$H+}
23+
uses
24+
{$IFDEF UNIX}
25+
cthreads, // MUST be first on Linux/macOS
26+
{$ENDIF}
27+
ThreadPool.Simple; // or ThreadPool.ProducerConsumer
28+
```
29+
30+
Windows does not need `cthreads` and is unaffected.
31+
32+
## What changed
33+
34+
- **README** — a prominent note at the top of Quick Start explaining the
35+
`cthreads` requirement, plus the `{$IFDEF UNIX}cthreads{$ENDIF}` guard added
36+
to every Quick Start and Installation snippet, and a reminder in the
37+
compilation Tip.
38+
- **API docs** — a platform note at the top of both
39+
`ThreadPool.Simple-API.md` and `ThreadPool.ProducerConsumer-API.md`.
40+
- **Roadmap** — "Planned/In Progress" dropped adaptive thread adjustment (it
41+
conflicts with the library's intentionally simple, fixed-count design) and
42+
added richer error handling, planned for 0.7.0.
43+
44+
> The examples in this repository already include the `cthreads` guard (added in
45+
> v0.6.0), so they build and run correctly on both platforms — see
46+
> `examples/Starter/Starter.lpr`.
47+
48+
## Upgrade notes
49+
50+
- **Nothing to change in your code.** If your program already runs correctly on
51+
Linux/macOS, it already has `cthreads` and is fine.
52+
- If you are *new* to the library on Linux/macOS, add the `cthreads` guard shown
53+
above as the first unit in your program.
54+
55+
## Full changelog
56+
57+
See [CHANGELOG.md](../CHANGELOG.md) for the complete version history.

‎package/lazarus/threadpool_fp.lpk‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -81,7 +81,7 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
8181
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
8282
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
8383
SOFTWARE. "/>
84-
<Version Minor="6"/>
84+
<Version Minor="6" Release="5"/>
8585
<Files>
8686
<Item>
8787
<Filename Value="..\..\src\ThreadPool.Simple.pas"/>

0 commit comments

Comments
 (0)