Base Classes

Classes in the main directory:

Welcome to the documentation page for the classes located in the main directory of this project. Below, you’ll find a summary of the key classes and their functionalities.

Summary

• Base classes
  • IRequest
  • Request<>
  • RequestReturn
  • RequestHandler
• Container
  • RequestContainer
  • ProgressableContainer
  • IProgressableRequest
• Implementation
  • OwnRequest

$\text{\color{orange}I\color{none}Request}$ Interface

The IRequest interface defines the properties and methods necessary for the RequestHandler to process an IRequest implementation.

Properties:

• State: Type: RequestState
  • Provides information about the state of the IRequest implementation.
• StateChanged: Type: EventHandler<RequestState>
  • Should be called when the state of the IRequest changes.
• Priority: Type: RequestPriority
  • Indicates the priority of the IRequest implementation.
• Task: Type: Task
  • Should represents the asynchronous state of the implementation (finished, failed, or running).
• Exception: Type: Nullable<AggregateException>
  • Should provide details of any exceptions that occurred during the execution of the IRequest.

Methods:

• StartRequestAsync: Type: Task
  • Initiates the execution of the IRequest implementation asynchronously.
• Start: Type: void
  • Deploys the IRequest implementation into the RequestHandler.
• Cancel: Type: void
  • Cancels all ongoing processes and disposes of the implementation.
• Pause: Type: void
  • Stops ongoing processes gracefully and saves their current state.
• TrySetIdle: Type: bool
  • Tries to set the State of the IRequest implementation to idle for manual processing by a RequestHandler.

$\text{Request&lt;\color{orange}TOptions\color{none},\color{green}TCompleated\color{none},\color{red}TFailed\color{none}&gt;}$ Abstract Class

The abstract Request<> class implements fundamental functionalities for managing requests within the RequestHandler. It implements IRequest and is generic, allowing for three type parameters.

Generic Parameters:

• $\text{\color{orange}TOptions}$: Type: RequestOptions<TCompleated, TFailed>
  • Specifies which RequestOptions should be used by the Request<>.
• $\text{\color{green}TCompleated}$: Type: None
  • Represents the return type when the Request<> completes successfully.
• $\text{\color{red}TFailed}$: Type: None
  • Represents the return type when the Request<> fails to run successfully after all retries.

Properties:

• AttemptCounter: Type: int
  • Keeps track of the number of retries for the Request<>.
• SynchronizationContext: Type: SynchronizationContext
  • Provides the synchronization context for syncing callback events.
• StartOptions: Type: TOptions
  • Holds the Options object passed during construction of the Request<>.
• Token: Type: CancellationToken
  • Indicates whether a Request was canceled.
• Task: Type: Task
  • Represents the asynchronous state of the object (finished, failed, or running).
• Exception: Type: AggregateException
  • Stores any exceptions thrown by the Request<>.
• DeployDelay: Type: TimeSpan
  • Specifies the time the Request<> waits before being deployed to the RequestHandler.
• State: Type: RequestState
  • Provides information about the state of the Request<>.
• StateChanged: Type: EventHandler<RequestState>
  • Invoked when the state of the Request<> changes.
• Priority: Type: RequestPriority
  • Indicates the priority of the Request<> within the RequestHandler.
• protected Options: Type: TOptions
  • Contains the modified Options object used by the Request<>.

Methods:

• Constructor:
  • Creates a Request<> object. You can pass a TOptions to customize its behavior.
• Start: Type: void
  • Deploys the request into the RequestHandler.
• Pause: Type: void
  • Pauses the RequestState.
• TrySetIdle: Type: bool
  • Attempts to set the state of the Request<> implementation to idle, either for manual addition to a RequestHandler or for manual execution using the IRequest.StartRequestAsync method.
• Cancel: Type: void
  • Cancels the Request<>, including the CancellationTokenSource, and sets the state to canceled.
• Wait: Type: void
  • Waits for the TaskCompletionSource to finish.
• Dispose: Type: void
  • Disposes of the Request<>.
• IRequest.StartRequestAsync: Type: Task
  • Handles the initial part of the execution.
• protected abstract RunRequestAsync: Type: Task<RequestReturn>
  • Must be implemented by the specific Request<> implementation.
  • Executes the main request logic and returns a RequestReturn object with relevant information.
• protected AutoStart: Type: void
  • Automatically starts the Request<> upon creation.
• private TryRunRequestAsync: Type: Task
  • Runs the RunRequestAsync method within a try-catch block and captures unhandled exceptions.
• private EvaluateRequest: Type: void
  • Evaluates whether the task ran successfully or encountered errors.
• private SetTaskState: Type: void
  • Sets the task state based on the evaluation from EvaluateRequest.
• private RegisterNewCTS: Type: void
  • Disposes the old CancellationTokenSource and registers a new one.
• private CreateNewCTS: Type: CancellationTokenSource
  • Creates a new CancellationTokenSource.
• private AddException: Type: void
  • Adds an exception to the AggregateException.
• private WaitAndDeploy: Type: Task
  • Asynchronously waits for the deploy delay time.

$\text{RequestReturn}$ Class

The RequestReturn class is an anonymous class used within the Request<> to hold return and notification objects during a Request<> run.

Properties:

• CompleatedReturn: Type: Nullable<TCompleated>
  • Description: Represents the object that will be returned by the RequestOptions<TCompleated, TFailed>.RequestCompleted delegate when the request completes successfully.
• FailedReturn: Type: Nullable<TFailed>
  • Description: Represents the object that will be returned by the RequestOptions<TCompleated, TFailed>.RequestFailed delegate when the request fails to run successfully after all retries.
• Successful: Type: bool
  • Description: Indicates whether the Request<> was successful.

$\text{RequestHandler}$ Class

The RequestHandler class manages all IRequest objects in the priority channel. It starts and restarts them if they fail. Additionally, it handles the degree of parallelism and manages the main cancellation token.

Properties:

• IsRunning: Type: bool
  • Indicates whether the RequestHandler is currently running or not handling any requests.
• StaticDegreeOfParallelism: Type: Nullable<int>
  • Gets or sets the static degree of parallelism. If set, it disables auto-parallelism. The default value is null, which enables auto-parallelism.
• AutoParallelism: Type: Func<int>
  • A function to dynamically calculate the parallelism while the handler is running.
• MaxParallelism: Type: int
  • The value that represents the highest possible degree of parallelism.
• CancellationToken: Type: CancellationToken
  • The main cancellation token of a Handler instance. It applies to all requests within the handler instance.
• MainRequestHandlers: Type: static RequestHandler[]
  • Two preset main handlers that can be used to handle requests.
• DefaultSynchronizationContext: Type: SynchronizationContext
  • A default synchronization context that targets the ThreadPool. It can be used for all IRequest implementations if needed.
• CountRequests: Type: int
  • Counts all IRequest objects that have not yet been handled.

Methods:

• Constructor:
  • Creates a RequestHandler object. You can pass IRequest objects to start them.
• AddRequest: Type: void
  • Adds one or more IRequest objects to the RequestHandler.
• UpdateAutoParallelism: Type: void
  • Calculates the auto-parallelism manually again.
• RunRequests: Type: void
  • Starts the RequestHandler if it is not running yet and runs all unhandled requests.
• Resume: Type: void
  • Resumes the RequestHandler if it was paused.
• Pause: Type: void
  • Pauses the RequestHandler, allowing all running requests to complete, but prevents new requests from starting if they fail.
• CreateCTS: Type: void
  • Creates a new CancellationTokenSource if the old one was canceled.
• CancelCTS: Type: void
  • Cancels the CancellationTokenSource and all IRequest objects in this RequestHandler.
• private RunChannel: Type: Task
  • Starts the asynchronous Priority Channel process.
• private HandleRequests: Type: Task
  • Handles an IRequest.
• static CancelMainCTS: Type: void
  • Cancels the CancellationTokenSource of the Main RequestHandlers.
• static CreateMainCTS: Type: void
  • Creates new CancellationTokenSources for the Main RequestHandlers.
• static ResumeMain: Type: void
  • Resumes the Main RequestHandlers if they were paused.
• static PauseMain: Type: void
  • Pauses the Main RequestHandlers.

$\text{RequestContainer&lt;\color{orange}TOptions\color{none}&gt;}$ Class

The RequestContainer<> class implements fundamental functionalities for grouping IRequest objects. It implements IEnumerable<TRequest> and IRequest. It is generic, allowing for one type of parameter.

Generic Parameter:

• $\text{\color{orange}TOptions}$: Type: IRequest
  • Specifies which IRequest implementation should be used for grouping.

Properties:

• Task: Type: Task
  • Represents the asynchronous state of the object (finished, failed, or running).
• Exception: Type: AggregateException
  • Stores any exceptions thrown by the contained IRequest objects.
• State: Type: RequestState
  • Provides information about the general state of the contained IRequest objects.
• StateChanged: Type: EventHandler<RequestState>
  • Invoked when the state of the RequestContainer<> changes.
• Priority: Type: RequestPriority
  • Not used. Always set to RequestState.Normal.
• SynchronizationContext: Type: SynchronizationContext
  • Provides the synchronization context for syncing callback events.
• Length: Type: int
  • Returns the length of the RequestContainer<>.

Methods:

• Constructor:
  • Creates a RequestContainer<> object. You can pass IRequest objects to add them to the container.
• Add: Type: void
  • Adds one IRequest object to the RequestContainer<> and applies the state of the RequestContainer<> to the IRequest object.
• AddRange: Type: void
  • Adds one or more IRequest objects to the RequestContainer<> and applies the state of the RequestContainer<> to all new IRequest objects.
• Remove: Type: void
  • Removes one IRequest object from the RequestContainer<>.
• IRequest.StartRequestAsync: Type: Task
  • Runs all IRequest objects in the RequestContainer<> one after another.
• Start: Type: void
  • Starts all IRequest objects.
• Pause: Type: void
  • Pauses all IRequest objects.
• TrySetIdle: Type: bool
  • Attempts to set the all states of the Request<> objects to idle.
• Cancel: Type: void
  • Cancels all IRequest objects.
• Dispose: Type: void
  • Disposes of all IRequest objects.
• private NewTaskCompletion: Type: void
  • Creates a new TaskCompletionSource.
• private CreateArrayWithNewItems: Type: void
  • Allocates new space for new IRequest objects.
• private OnStateChanged: Type: void
  • Is called when one request changes its state and invokes CalculateState.
• private CalculateState: Type: RequestState
  • Calculates the new state of the RequestContainer<>.
• static MergeContainers: Type: RequestContainer<TRequest>
  • Creates a new RequestContainer<> object that contains all IRequest objects. It does not contain the passed RequestContainer objects; only the IRequest objects are included.

$\text{ProgressableContainer&lt;\color{orange}TOptions\color{none}&gt;}$

The ProgressableContainer<> combines IProgressableRequest objects and inherits from RequestContainer<>. It is a generic class, allowing for one type of parameter.

Generic Parameter:

• $\text{\color{orange}TOptions}$: Type: IProgressableRequest
  • Specifies which IProgressableRequest implementation should be used for grouping.

Properties:

• Progress: Type: Progress<float>
  • Represents the merged progress of all IProgressableRequest objects.

Methods:

• Constructor:
  • Creates a ProgressableContainer<> object. You can pass IProgressableRequest objects to add them to the container.
• Add: Type: void
  • Adds one IProgressableRequest object to the ProgressableContainer<> and updates the overall progress.
• AttachProgress: Type: void
  • Adds a Progress<float> instance to the CombinableProgress<float> of the container.
• static MergeContainers: Type: ProgressableContainer<TRequest>
  • Creates a new ProgressableContainer<> object that contains all IProgressableRequest objects. It does not include the passed ProgressableContainer<> objects; only the IProgressableRequest objects are included.
• AddRange: Type: void
  • Adds one or more IProgressableRequest objects to the ProgressableContainer<> and updates the overall progress.
• Remove: Type: void
  • Removes one IProgressableRequest object from the ProgressableContainer<>.

$\text{\color{orange}I\color{none}ProgressableRequest}$ Interface

The IProgressableRequest interface provides an interface to be used in ProgressableContainer<>. It implements the IRequest interface.

Properties:

• Progress: Type: Progress<float>
  • Represents the progress of an IRequest implementation.

$\text{\color{green}Own\color{none}Request}$ Class

The OwnRequest class implements the basic functionality of the Request base class. It utilizes VoidStruct for both the $\text{\color{green}TCompleated}$ and $\text{\color{red}TFailed}$ parameters.

Methods:

• Constructor:
  • Creates a Request<> object. You need to provide a Func<CancellationToken, Task<bool>> and can optionally pass a RequestOptions<VoidStruct, VoidStruct> to customize its behavior. The constructor also calls AutoStart.
• protected RunRequestAsync: Type: Task<RequestReturn>
  • Invokes the Func<CancellationToken, Task<bool>> object passed in the constructor.