gabr42/omnithreadlibrary/claude-skill

OmniThreadLibrary (OTL) Reference

Source: "Parallel Programming with OmniThreadLibrary" by Primož Gabrijelčič (covers OTL 3.09) Library: Windows-only (32-bit and 64-bit; VCL, service and console applications; no FireMonkey, no FreePascal). Delphi 2007 or newer (up to and including Delphi 13 Florence). The high-level API requires Delphi 2009+; Delphi XE or newer is recommended (some parts do not work in 2009/2010 due to compiler bugs). Channel/Select/Merge/Race require Delphi XE+. Non-Windows support was removed in 3.09 (see OmniThreadLibrary-NG). License: BSD — free for any use. Version tags: [3.07.2], [3.09] etc. in the reference files mark the OTL release that introduced a feature.

Units Overview

For the complete list of every unit in the library — including internal/support units (registration, logging, benchmarking, platform compatibility, etc.) not covered above — see unit-index.md.

Reference files

Read the file for the area you need; each starts with a table of contents.

Patterns and Best Practices

Choosing the Right Abstraction

NumTasks Conventions

Used across all high-level abstractions:

• Positive N → exactly N worker tasks
• Negative -N → [available cores] - N tasks, but never fewer than 1 [3.07.10]
• 0 → exception

OnStop vs OnStopInvoke

• OnStop(TProc): called from worker thread (be careful with UI)
• OnStop(TOmniTaskStopDelegate): called from worker thread; use task.Invoke(...) for main-thread code
• OnStopInvoke [3.07.2]: automatically invokes in owner thread — simplest approach

Lifecycle of Async Abstractions (NoWait)

When using NoWait, store the interface in a field — never a local variable:

// CORRECT pattern using OnStopInvoke [3.07.2]:
FLoop := Parallel.ForEach(1, N).NoWait;
FLoop.OnStopInvoke(
  procedure
  begin
    FLoop := nil;  // executed in owner thread after all workers done
  end);
FLoop.Execute(procedure (const value: integer) begin ... end);
 
// WRONG — loop interface destroyed immediately:
Parallel.ForEach(1, N).NoWait.Execute(...);

Join/ParallelTask with NoWait must be waited for

[3.09] Destroying a Parallel.Join or Parallel.ParallelTask started with NoWait without calling WaitFor (or Terminate) first raises an exception from the destructor.

Compile-time options

• OTL_OLDCPU [3.09]: only relevant for 32-bit. No longer defined by default; the lock-free queues use SSE2 (MoveDPtr) and the OtlContainers initialization raises an exception at startup on a CPU without SSE2. Define OTL_OLDCPU in the project options for CPUs without SSE2.
• DSiNoTimerResolution [3.09]: stops DSiWin32 from raising the system timer resolution to 1 ms (timeBeginPeriod(1)) for the life of the process; Sleep(1) is then rounded up to ~15.6 ms.
• BCB (C++Builder): some overloaded properties and Release methods get different names in the generated headers (AsArrayItemByName/AsArrayItemOV, ItemByName/ItemOV, Leave for IOmniCriticalSection.Release/IOmniResourceCount.Release).

TOmniWorker Resource Management

Always allocate resources in Initialize and release in Cleanup — never in constructor/destructor:

TMyWorker = class(TOmniWorker)
strict private
  FConnection: TDatabaseConnection;
protected
  function  Initialize: boolean; override;
  procedure Cleanup; override;
public
  procedure MsgProcessRequest(var msg: TOmniMessage); message MSG_PROCESS;
end;
 
function TMyWorker.Initialize: boolean;
begin
  Result := inherited Initialize;
  if Result then
    FConnection := TDatabaseConnection.Create;
end;
 
procedure TMyWorker.Cleanup;
begin
  FreeAndNil(FConnection);
  inherited Cleanup;
end;

Anonymous Method Closure Capture

CRITICAL: Anonymous methods capture variables by reference. In loops, all closures share the same variable reference.

// BROKEN — all callbacks use last handler value:
for sub in subscriptions do begin
  handler := GetHandler(sub);
  QueueCallback(procedure begin handler(); end);  // BUG!
end;
 
// CORRECT — helper method captures by value:
function MakeCallback(handler: THandlerProc): TProc;
begin
  Result := procedure begin handler(); end;
end;
 
for sub in subscriptions do
  QueueCallback(MakeCallback(GetHandler(sub)));

Inline variables do NOT fix this. Only the helper method pattern works.

Exception Handling Summary

Parallel.For vs Parallel.ForEach

• Parallel.For: splits range into sequential blocks, one block per task. Faster. Has an Int64 overload [3.09].
• Parallel.ForEach: work-stealing scheduler, aggregation, PreserveOrder, cancellation. More powerful but slower.

Use Parallel.For for CPU-bound loops over numeric ranges without ordering requirements.

Combining OnMessage and OnTerminated (Low-Level)

FTask := CreateTask(TMyWorker.Create)
  .OnMessage(WM_RESULT,
    procedure(const task: IOmniTaskControl; const msg: TOmniMessage)
    begin
      ProcessResult(msg.MsgData.AsString);
    end)
  .OnTerminated(
    procedure
    begin
      btnStart.Enabled := true;
      FTask := nil;
    end)
  .Run;