From bb6970ae1569540fe9a25975920a9e21a87d24f6 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 27 Nov 2025 22:41:53 +0000 Subject: [PATCH 1/2] Initial plan From d11ccbea60e981f90f48040dcb3a2560cae96dff Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 27 Nov 2025 22:49:17 +0000 Subject: [PATCH 2/2] Add documentation for DisableBackgroundServices feature from PR #413 Co-authored-by: SpaceOgre <381657+SpaceOgre@users.noreply.github.com> --- docs/.vitepress/config.ts | 3 +- .../configuration/core-configuration.md | 4 + .../core-configuration/background-services.md | 181 ++++++++++++++++++ .../configuration/core-configuration/index.md | 4 + 4 files changed, 191 insertions(+), 1 deletion(-) create mode 100644 docs/api-reference/configuration/core-configuration/background-services.md diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 9efdf45..b083bda 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -165,7 +165,8 @@ export default defineConfig({ { text: 'Overview', link: '/api-reference/configuration/core-configuration' }, { text: 'Scheduler', link: '/api-reference/configuration/core-configuration/scheduler-configuration' }, { text: 'Exception Handling', link: '/api-reference/configuration/core-configuration/exception-handling' }, - { text: 'Start Mode', link: '/api-reference/configuration/core-configuration/start-mode' } + { text: 'Start Mode', link: '/api-reference/configuration/core-configuration/start-mode' }, + { text: 'Background Services', link: '/api-reference/configuration/core-configuration/background-services' } ] }, { diff --git a/docs/api-reference/configuration/core-configuration.md b/docs/api-reference/configuration/core-configuration.md index 4d225fe..8504628 100644 --- a/docs/api-reference/configuration/core-configuration.md +++ b/docs/api-reference/configuration/core-configuration.md @@ -13,6 +13,9 @@ Set up global exception handlers for job execution errors. ### [Start Mode](./core-configuration/start-mode) Control when TickerQ starts processing jobs. +### [Background Services](./core-configuration/background-services) +Enable or disable background job processing services for queue-only mode. + ## Quick Example ```csharp @@ -35,5 +38,6 @@ builder.Services.AddTickerQ(options => - [Scheduler Configuration](./core-configuration/scheduler-configuration) - Detailed scheduler options - [Exception Handling](./core-configuration/exception-handling) - Global exception handler setup - [Start Mode](./core-configuration/start-mode) - Application startup control +- [Background Services](./core-configuration/background-services) - Enable or disable background processing - [Configuration Overview](./index) - All configuration sections diff --git a/docs/api-reference/configuration/core-configuration/background-services.md b/docs/api-reference/configuration/core-configuration/background-services.md new file mode 100644 index 0000000..37edaba --- /dev/null +++ b/docs/api-reference/configuration/core-configuration/background-services.md @@ -0,0 +1,181 @@ +# Background Services + +Control whether TickerQ registers and runs background job processing services. + +## DisableBackgroundServices + +Disable registration of background services for queue-only mode. + +**Method:** +```csharp +TickerOptionsBuilder DisableBackgroundServices(); +``` + +**Example:** +```csharp +builder.Services.AddTickerQ(options => +{ + // Only register managers for queuing jobs, no processing + options.DisableBackgroundServices(); +}); +``` + +## Background Services + +By default, TickerQ registers the following background services: + +| Service | Purpose | +|---------|---------| +| `TickerQSchedulerBackgroundService` | Main scheduler for job execution | +| `TickerQFallbackBackgroundService` | Fallback job checking mechanism | +| `TickerQDispatcher` | Dispatches jobs to worker threads | +| `TickerQTaskScheduler` | Manages worker thread pool | + +When `DisableBackgroundServices()` is called, these services are replaced with no-operation implementations that do not process jobs. + +## Queue-Only Mode + +When background services are disabled, TickerQ operates in "queue-only" mode: + +- **Available**: `ITimeTickerManager` and `ICronTickerManager` for queuing jobs +- **Available**: `ITickerQHostScheduler` (no-op implementation) +- **Available**: `ITickerQDispatcher` (no-op implementation, `IsEnabled = false`) +- **Not Available**: Actual job processing and execution + +Jobs queued in this mode will be stored (in-memory or database) but won't execute until processed by an application with background services enabled. + +## Use Cases + +### Web API for Job Queuing Only + +Run a lightweight API server that only queues jobs, with separate worker instances processing them: + +```csharp +// API Server - queue-only mode +builder.Services.AddTickerQ(options => +{ + options.DisableBackgroundServices(); +}); + +// Worker Server - with processing +builder.Services.AddTickerQ(options => +{ + // Default: background services enabled + options.ConfigureScheduler(scheduler => + { + scheduler.MaxConcurrency = 20; + }); +}); +``` + +### Microservices Architecture + +Separate job creation from job processing across different services: + +```csharp +// Order Service - creates jobs, doesn't process +builder.Services.AddTickerQ(options => +{ + options.DisableBackgroundServices(); +}); + +// Worker Service - processes jobs +builder.Services.AddTickerQ(options => +{ + options.ConfigureScheduler(scheduler => + { + scheduler.NodeIdentifier = "order-worker-01"; + }); +}); +``` + +### Testing Scenarios + +Queue jobs without executing them during tests: + +```csharp +services.AddTickerQ(options => +{ + options.DisableBackgroundServices(); +}); + +// Jobs can be queued and verified without execution +await timeTickerManager.AddAsync(new TTimeTicker +{ + Function = "TestFunction", + ExecutionTime = DateTime.UtcNow +}); +``` + +## Behavior Details + +### Dispatcher Behavior + +When background services are disabled: + +```csharp +var dispatcher = serviceProvider.GetRequiredService(); + +// Returns false - dispatcher is not functional +Console.WriteLine(dispatcher.IsEnabled); // false + +// DispatchAsync is a no-op +await dispatcher.DispatchAsync(contexts); // Does nothing +``` + +### Scheduler Behavior + +When background services are disabled: + +```csharp +var scheduler = serviceProvider.GetRequiredService(); + +// Always returns false +Console.WriteLine(scheduler.IsRunning); // false + +// Start/Stop are no-ops +await scheduler.StartAsync(); // Does nothing +await scheduler.StopAsync(); // Does nothing +``` + +### Manager Behavior + +Managers work normally regardless of background services setting: + +```csharp +var timeManager = serviceProvider.GetRequiredService>(); + +// Works normally - job is persisted +await timeManager.AddAsync(new TTimeTicker +{ + Function = "MyFunction", + ExecutionTime = DateTime.UtcNow.AddHours(1) +}); + +// Job won't execute locally, but will be processed by nodes with background services enabled +``` + +## Combining with Other Options + +```csharp +builder.Services.AddTickerQ(options => +{ + // Disable background services + options.DisableBackgroundServices(); + + // Exception handler still works for manager operations + options.SetExceptionHandler(); + + // Seeding still works + options.UseTickerSeeder( + async timeManager => { /* seed time tickers */ }, + async cronManager => { /* seed cron tickers */ } + ); +}); +``` + +## See Also + +- [Start Mode](./start-mode) - Control when processing starts +- [Scheduler Configuration](./scheduler-configuration) - Worker thread settings +- [Core Configuration Overview](./index) - All core configuration options diff --git a/docs/api-reference/configuration/core-configuration/index.md b/docs/api-reference/configuration/core-configuration/index.md index c63ad69..84fb4c0 100644 --- a/docs/api-reference/configuration/core-configuration/index.md +++ b/docs/api-reference/configuration/core-configuration/index.md @@ -13,6 +13,9 @@ Set up global exception handlers for job execution errors. ### [Start Mode](./start-mode) Control when TickerQ starts processing jobs. +### [Background Services](./background-services) +Enable or disable background job processing services for queue-only mode. + ### Request Serialization Control how ticker request payloads are serialized and stored (plain JSON bytes or GZip-compressed). @@ -71,4 +74,5 @@ builder.Services.AddTickerQ(options => - [Scheduler Configuration](./scheduler-configuration) - Detailed scheduler options - [Exception Handling](./exception-handling) - Global exception handler setup - [Start Mode](./start-mode) - Application startup control +- [Background Services](./background-services) - Enable or disable background processing - [Configuration Overview](../index) - All configuration sections