Table of Contents

Interface IDispatchScheduler

Namespace
Excalibur.Dispatch.Delivery
Assembly
Excalibur.Dispatch.Abstractions.dll

Defines the contract for scheduling message dispatch operations with support for both one-time and recurring execution patterns.

public interface IDispatchScheduler
Extension Methods

Remarks

The dispatch scheduler is a fundamental component for time-based message processing in distributed systems, enabling deferred execution, periodic tasks, and complex scheduling scenarios. It provides flexibility for various temporal messaging patterns while maintaining reliability and scalability.

Scheduling Patterns:

The scheduler supports multiple execution patterns:

  • One-time scheduling for delayed message processing.
  • Cron-based recurring schedules for complex timing requirements.
  • Interval-based recurring schedules for simple periodic tasks.
  • Timezone-aware scheduling for global distributed systems.

Reliability Features:

Implementations should provide:

  • Persistent schedule storage to survive system restarts.
  • Missed execution handling for system downtime scenarios.
  • Duplicate execution prevention through idempotency mechanisms.
  • Monitoring and observability for scheduled job tracking.

Scalability Considerations:

The scheduler should be designed for:

  • High-volume scheduling with efficient storage and retrieval.
  • Distributed execution across multiple nodes.
  • Load balancing for scheduled job processing.
  • Graceful degradation under high load conditions.

Methods

ScheduleOnceAsync<TMessage>(DateTimeOffset, TMessage, CancellationToken)

Schedules a message for one-time dispatch at the specified future time.

Task ScheduleOnceAsync<TMessage>(DateTimeOffset executeAtUtc, TMessage message, CancellationToken cancellationToken) where TMessage : class

Parameters

executeAtUtc DateTimeOffset

The UTC timestamp when the message should be dispatched. Must be in the future.

message TMessage

The message instance to dispatch at the scheduled time. Cannot be null.

cancellationToken CancellationToken

Token to observe for cancellation requests during the scheduling operation.

Returns

Task

A task representing the asynchronous scheduling operation.

Type Parameters

TMessage

The message type to schedule. Must be a reference type to support serialization.

Remarks

One-time scheduling is ideal for scenarios such as:

Use Cases:

  • Delayed notification delivery (e.g., reminder emails after registration).
  • Timeout handling for long-running processes.
  • Scheduled data processing tasks (e.g., report generation).
  • Deferred cleanup operations after resource usage.

Execution Guarantees:

The message will be dispatched approximately at the specified time, subject to:

  • System clock accuracy and scheduler polling intervals
  • Load conditions and processing capacity at execution time
  • Network latency and message broker availability

Error Handling:

If scheduling fails, the operation will throw an exception. If execution fails at the scheduled time, the behavior depends on the configured retry policies and dead letter handling strategies.

Exceptions

ArgumentNullException

Thrown when message is null.

ArgumentException

Thrown when executeAtUtc is in the past.

OperationCanceledException

Thrown when the operation is cancelled.

ScheduleRecurringAsync<TMessage>(string, CronRecurrenceProfile, TMessage, CancellationToken)

Schedules cron work using the configured default zone and an explicit transition profile.

Task ScheduleRecurringAsync<TMessage>(string cronExpression, CronRecurrenceProfile profile, TMessage message, CancellationToken cancellationToken) where TMessage : class

Parameters

cronExpression string

The cron expression.

profile CronRecurrenceProfile

The explicitly selected supported transition declaration.

message TMessage

The message to persist.

cancellationToken CancellationToken

The cancellation token.

Returns

Task

The scheduling operation.

Type Parameters

TMessage

The message type.

Remarks

The resolved installed zone and primitive profile pair are persisted; no implicit transition-zone default is chosen.

ScheduleRecurringAsync<TMessage>(string, TimeZoneInfo, CronRecurrenceProfile, TMessage, CancellationToken)

Schedules cron work using an installed named zone and explicit transition profile.

Task ScheduleRecurringAsync<TMessage>(string cronExpression, TimeZoneInfo timeZone, CronRecurrenceProfile profile, TMessage message, CancellationToken cancellationToken) where TMessage : class

Parameters

cronExpression string

The cron expression.

timeZone TimeZoneInfo

An installed timezone that can be resolved from its identifier after restart.

profile CronRecurrenceProfile

The explicitly selected supported transition declaration.

message TMessage

The message to persist.

cancellationToken CancellationToken

The cancellation token.

Returns

Task

The scheduling operation.

Type Parameters

TMessage

The message type.

Remarks

Custom timezone identifiers cannot roundtrip through the persisted row and are rejected. Existing overloads without a profile remain valid only for installed transition-free zones. Adding this member is an intentional source break for custom scheduler implementations.

ScheduleRecurringAsync<TMessage>(string, TMessage, CancellationToken)

Schedules a message for recurring dispatch based on a cron expression schedule.

Task ScheduleRecurringAsync<TMessage>(string cronExpression, TMessage message, CancellationToken cancellationToken) where TMessage : class

Parameters

cronExpression string

The cron expression defining the execution schedule. Must be a valid cron format.

message TMessage

The message instance template to dispatch on each scheduled execution. Cannot be null.

cancellationToken CancellationToken

Token to observe for cancellation requests during the scheduling operation.

Returns

Task

A task representing the asynchronous scheduling operation.

Type Parameters

TMessage

The message type to schedule. Must be a reference type to support serialization.

Remarks

Cron-based scheduling provides powerful flexibility for complex timing requirements:

Cron Expression Support:

Standard cron format: "* * * * * *" (seconds, minutes, hours, day of month, month, day of week).

  • "0 0 12 * * ?" - Daily at noon.
  • "0 0/15 * * * ?" - Every 15 minutes.
  • "0 0 9 * * MON-FRI" - Weekdays at 9 AM.
  • "0 0 0 1 * ?" - First day of each month.

Advanced Features:

Implementations may support:

  • Timezone-aware execution for global systems
  • Missed execution policies for system downtime handling
  • Maximum execution count limits for finite recurring schedules
  • Dynamic schedule modification during runtime

Message Templating:

The provided message serves as a template. Each execution may create a new message instance with updated timestamps or execution-specific data.

Exceptions

ArgumentNullException

Thrown when cronExpression or message is null.

ArgumentException

Thrown when cronExpression is invalid or malformed.

OperationCanceledException

Thrown when the operation is cancelled.

ScheduleRecurringAsync<TMessage>(TimeSpan, TMessage, CancellationToken)

Schedules a message for recurring dispatch at regular time intervals.

Task ScheduleRecurringAsync<TMessage>(TimeSpan interval, TMessage message, CancellationToken cancellationToken) where TMessage : class

Parameters

interval TimeSpan

The time interval between consecutive message dispatches. Must be positive.

message TMessage

The message instance template to dispatch on each scheduled execution. Cannot be null.

cancellationToken CancellationToken

Token to observe for cancellation requests during the scheduling operation.

Returns

Task

A task representing the asynchronous scheduling operation.

Type Parameters

TMessage

The message type to schedule. Must be a reference type to support serialization.

Remarks

Interval-based scheduling provides simple, predictable recurring execution:

Interval Patterns:

Common interval scheduling patterns include:

  • Health checks every 30 seconds: TimeSpan.FromSeconds(30).
  • Data synchronization every 5 minutes: TimeSpan.FromMinutes(5).
  • Daily report generation: TimeSpan.FromDays(1).
  • Hourly cleanup tasks: TimeSpan.FromHours(1).

Execution Timing:

The first execution occurs after the specified interval from the scheduling time. Subsequent executions are scheduled based on the completion time of the previous execution, preventing overlap and accumulation of delayed executions.

Performance Considerations:

Very short intervals (seconds or less) may impact system performance. Consider the processing time of the message and system capacity when selecting intervals for high-frequency recurring schedules.

Exceptions

ArgumentNullException

Thrown when message is null.

ArgumentOutOfRangeException

Thrown when interval is zero or negative.

OperationCanceledException

Thrown when the operation is cancelled.