Implement Retry Mechanism and Concurrency Control for Jobs

CHANGELOG.md

@@ -6,6 +6,24 @@ All notable changes to **NCronJob** will be documented in this file. The project
 
 ## [Unreleased]
 
+## [2.1.0] - 2024-04-23
+
+### Added
+- **Retry Mechanism:** Improved robustness of job executions, especially in cases of transient failures. Includes exponential backoff and fixed interval strategies.
+- **Concurrency Control:** Introduced a `SupportsConcurrency` attribute to provide fine-grained control over the concurrency behavior of individual jobs. This attribute allows specifying the maximum degree of parallelism.
+- **New WaitForJobsOrTimeout:** Added an enhanced version of `WaitForJobsOrTimeout` to the Tests project that allows time advancement for each run, providing more precise control over test execution timing.
+- **Cancellation Support:** Jobs now support graceful cancellation during execution and SIGTERM.
+
+### Changed
+- **Concurrency Management:** Implemented improved global concurrency handling techniques within `CronScheduler`. This change enhances flexibility and scalability in managing job executions.
+- **Async Job Executions:** Job executions are now fully async from the moment the scheduler triggers the job, ensuring better performance and resource utilization.
+
+### Fixed
+- **Test Framework Bugs:** Addressed specific bugs in the testing framework, ensuring that all tests are now passing and provide reliable results.
+
+### Contributors
+- Support for concurrent jobs and retries, as well as overall improvements, implemented by [@falvarez1](https://github.com/falvarez1) in PR [#21](https://github.com/linkdotnet/NCronJob/pull/21).
+
 ## [2.0.5] - 2024-04-19
 
 ### Changed

README.md

@@ -220,6 +220,142 @@ Services.AddNCronJob(options =>
 });
 ```
 
+## Retry Support
+
+The new Retry support provides a robust mechanism for handling transient failures by retrying failed operations. This feature is implemented using the `RetryPolicy` attribute that can be applied to any class implementing the `IJob` interface.
+
+### How It Works
+
+The `RetryPolicy` attribute allows you to specify the number of retry attempts and the strategy for handling retries. There are two built-in retry strategies:
+- **ExponentialBackoff:** Increases the delay between retry attempts exponentially.
+- **FixedInterval:** Keeps the delay between retry attempts consistent.
+
+### Using Retry Policies
+
+Here are examples of how to use the built-in retry policies:
+
+#### Example 1: Basic Retry Policy, defaults to Exponential Backoff
+
+```csharp
+[RetryPolicy(retryCount: 4)]
+public class RetryJob(ILogger<RetryJob> logger) : IJob
+{
+    public async Task RunAsync(JobExecutionContext context, CancellationToken token)
+    {
+        var attemptCount = context.Attempts;
+
+        if (attemptCount <= 3)
+        {
+            logger.LogWarning("RetryJob simulating failure.");
+            throw new InvalidOperationException("Simulated operation failure in RetryJob.");
+        }
+
+        logger.LogInformation($"RetryJob with Id {context.Id} was attempted {attemptCount} times.");
+        await Task.CompletedTask;
+    }
+}
+```
+
+#### Example 2: Fixed Interval
+
+```csharp
+[RetryPolicy(4, PolicyType.FixedInterval)]
+public class FixedIntervalRetryJob(ILogger<FixedIntervalRetryJob> logger) : IJob
+{
+    public async Task RunAsync(JobExecutionContext context, CancellationToken token)
+    {
+        var attemptCount = context.Attempts;
+
+        if (attemptCount <= 3)
+        {
+            logger.LogWarning("FixedIntervalRetryJob simulating failure.");
+            throw new InvalidOperationException("Simulated operation failure in FixedIntervalRetryJob.");
+        }
+
+        logger.LogInformation($"FixedIntervalRetryJob with Id {context.Id} was attempted {attemptCount} times.");
+        await Task.CompletedTask;
+    }
+}
+```
+
+### Advanced: Custom Retry Policies
+
+You can also create custom retry policies by implementing the `IPolicyCreator` interface. This allows you to define complex retry logic tailored to your specific needs.
+
+```csharp
+[RetryPolicy<MyCustomPolicyCreator>(retryCount:4, delayFactor:1)]
+public class CustomPolicyJob(ILogger<CustomPolicyJob> logger) : IJob
+{
+    public async Task RunAsync(JobExecutionContext context, CancellationToken token)
+    {
+        var attemptCount = context.Attempts;
+
+        if (attemptCount <= 3)
+        {
+            logger.LogWarning("FixedIntervalRetryJob simulating failure.");
+            throw new InvalidOperationException("Simulated operation failure in FixedIntervalRetryJob.");
+        }
+
+        logger.LogInformation($"CustomPolicyJob with Id {context.Id} was attempted {attemptCount} times.");
+        await Task.CompletedTask;
+    }
+}
+
+public class MyCustomPolicyCreator : IPolicyCreator
+{
+    public IAsyncPolicy CreatePolicy(int maxRetryAttempts = 3, double delayFactor = 2)
+    {
+        return Policy.Handle<Exception>()
+            .WaitAndRetryAsync(maxRetryAttempts,
+                retryAttempt => TimeSpan.FromSeconds(Math.Pow(delayFactor, retryAttempt)));
+    }
+}
+```
+
+## Concurrency Support
+
+Concurrency support allows multiple instances of the same job type to run simultaneously, controlled by the `SupportsConcurrency` attribute. This feature is crucial for efficiently managing jobs that are capable of running in parallel without interference.
+
+### How It Works
+
+The `SupportsConcurrency` attribute specifies the maximum degree of parallelism for job instances. This means you can define how many instances of a particular job can run concurrently, optimizing performance and resource utilization based on the nature of the job and the system capabilities.
+
+### Using the SupportsConcurrency Attribute
+
+Here is an example of how to apply this attribute to a job:
+
+#### Example: Concurrency in Jobs
+
+```csharp
+[SupportsConcurrency(10)]
+public class ConcurrentJob : IJob
+{
+    private readonly ILogger<ConcurrentJob> logger;
+
+    public ConcurrentJob(ILogger<ConcurrentJob> logger)
+    {
+        this.logger = logger;
+    }
+
+    public async Task RunAsync(JobExecutionContext context, CancellationToken token)
+    {
+        logger.LogInformation($"ConcurrentJob with Id {context.Id} is running.");
+        // Simulate some work by delaying
+        await Task.Delay(5000, token);
+        logger.LogInformation($"ConcurrentJob with Id {context.Id} has completed.");
+    }
+}
+```
+
+### Important Considerations
+
+#### Ensuring Job Idempotency
+When using concurrency, it's essential to ensure that each job instance is idempotent. This means that even if the job is executed multiple times concurrently or sequentially, the outcome and side effects should remain consistent, without unintended duplication or conflict.
+
+#### Resource Allocation Caution
+Jobs that are marked to support concurrency should be designed carefully to avoid contention over shared resources. This includes, but is not limited to, database connections, file handles, or any external systems. In scenarios where shared resources are unavoidable, proper synchronization mechanisms or concurrency control techniques, such as semaphores, mutexes, or transactional control, should be implemented to prevent race conditions and ensure data integrity.
+
+
 ## Support & Contributing
 
 Thanks to all [contributors](https://github.com/linkdotnet/NCronJob/graphs/contributors) and people that are creating