Class PoolOptions

Namespace

CobaltPdf

Assembly

CobaltPdf.dll

Configuration options for the CobaltPdf browser pool.

public class PoolOptions

Inheritance

object

PoolOptions

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

Pass an instance of this class to Configure(Action<PoolOptions>) at application startup. For common deployment targets, use the presets in CloudEnvironment rather than setting flags manually:

// Docker / Linux container
CobaltEngine.Configure(CloudEnvironment.ConfigureForDocker);

// Azure Functions Premium Plan
CobaltEngine.Configure(CloudEnvironment.ConfigureForAzure);

// Custom override on top of a preset
CobaltEngine.Configure(o =>
{
    CloudEnvironment.ConfigureForDocker(o);
    o.MaxSize = 4;
});

Properties

BrowserLeaseTimeout

The maximum time a caller will wait for a free browser lease before a TimeoutException is thrown.

public TimeSpan BrowserLeaseTimeout { get; set; }

Property Value

TimeSpan

Default: 30 seconds

Remarks

This timeout is combined (via a linked CancellationTokenSource) with any CancellationToken passed to the render method, so whichever fires first wins.

ExtraArgs

Raw Chromium command-line flags appended to every browser launch.

public List<string> ExtraArgs { get; set; }

Property Value

List<string>

Remarks

On Linux the following flags are added automatically as safe defaults: --no-sandbox, --disable-gpu, and --disable-dev-shm-usage. You do not need to add them manually. The CloudEnvironment presets will skip duplicates if you apply one on top of the defaults.

Common flags:

Flag	When to use
--no-sandbox	Always required on Linux (added automatically)
--disable-dev-shm-usage	Docker / limited /dev/shm (added automatically on Linux)
--disable-gpu	Headless servers without a GPU (added automatically on Linux)
--single-process	Memory-constrained environments (Azure App Service, AWS Lambda)
--proxy-server=host:port	Route Chromium traffic through a proxy
--ignore-certificate-errors	Self-signed certs during development

MaxQueueDepth

Backpressure limit: the maximum number of render callers allowed to wait for a free browser once all MaxSize slots are in use. When this many requests are already queued and another arrives, the pool fast-fails it with a PoolBusyException instead of making it wait out the full BrowserLeaseTimeout — letting the host return a deliberate "server busy" response (HTTP 503 + Retry-After) rather than a slow, opaque timeout.

public int MaxQueueDepth { get; set; }

Property Value

int

Default: 0 (unbounded)

Remarks

Default 0 = unbounded queue, preserving the historical behaviour exactly (callers wait up to BrowserLeaseTimeout and then receive a TimeoutException). Set a small positive number (e.g. 2× MaxSize) on a load-bearing endpoint so traffic spikes shed cleanly instead of piling up. Mirrors the CobaltPDF.WebKit edition.

MaxSize

The maximum number of concurrent browser instances allowed in the pool.

public int MaxSize { get; set; }

Property Value

int

Default: host-aware (see remarks). Override for tuned hosts.

Remarks

Render requests that arrive when all leases are taken will wait up to BrowserLeaseTimeout before throwing a TimeoutException. Must be ≥ 1.

Default: auto-sized to fit the host, as the smaller of (a) the vCPU count and (b) how many browsers fit in ~75% of detected memory at ~400 MB each — then clamped to 1–8. Chromium browsers are memory-heavy, so on constrained hosts (e.g. 8 vCPU but a 2 GB container) sizing by cores alone would OOM; this picks whichever resource runs out first. A 2-vCPU/3.5 GB B2 → 2; a 1-vCPU B1 → 1; an 8-vCPU/2 GB container → ~3 (memory-capped). Falls back to the clamped vCPU count if memory can't be detected. Always overridable.

MaxUsesPerBrowser

The maximum number of render operations a single browser instance will serve before it is recycled (closed and replaced with a fresh instance).

public int MaxUsesPerBrowser { get; set; }

Property Value

int

Default: 100

Remarks

Recycling prevents gradual memory growth from long-running browser processes. Lower this value if you observe increasing memory usage over time. Must be ≥ 1.

MinSize

The minimum number of browser instances to keep warm in the pool at all times.

public int MinSize { get; set; }

Property Value

int

Default: 1

Remarks

Set to 0 for lazy initialisation (browsers started on first request). Set to 1 or higher to eliminate cold-start latency on the first render. Must be ≥ 0 and ≤ MaxSize.