Fix descriptions

Add RequestContainer IRequest.StartRequestAsync()

Author: Meyn

LICENSE.txt

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 Shard
+Copyright (c) 2024 Shard
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,29 +1,34 @@
 [![NuGet](https://img.shields.io/nuget/vpre/Shard.Requests)](https://www.nuget.org/packages/Shard.Requests) [![Downloads](https://img.shields.io/nuget/dt/Shard.Requests)](https://www.nuget.org/packages/Shard.Requests) [![License](https://img.shields.io/github/license/TypNull/requests.svg)](https://github.com/TypNull/requests/blob/master/LICENSE) ![Maintainability](https://img.shields.io/badge/Maintainability%20Index-86%25-brightgreen)
 # Requests
+## 🌟 What Is Requests?
 
-Requests is a software library for C# .NET 6 that enables handling of requests in a parallel asynchronous state as Request objects.
-The library utilizes a priority channel to efficiently and systematically handle requests. 
-The priority channel ensures that high-priority requests are processed before low-priority requests. 
-This library is versatile and can be used for HTTP requests or other CPU-intensive tasks such as directory searching. 
+**Requests** is library for C# .NET 6; it's your trusty sidekick in the world of handling requests. Imagine a friendly companion that takes care of your requests, ensuring they're processed efficiently and systematically. Whether you're dealing with HTTP requests or tackling CPU-intensive tasks like directory searching.
 
-It has been specifically designed to be flexible and customizable, allowing developers to tailor the library to their specific needs. 
-Requests is an efficient and organized solution that simplifies the process of handling requests in C# .NET 6-based applications.
+## 🚀 Why Choose Requests?
 
-## Installation
+- **Priority Magic**: Our priority channel ensures that high-priority requests get the VIP treatment—they're processed before the rest. No more waiting in line!
+- **Flexibility at Its Best**: Requests is designed to be as flexible as possible. Customize it to fit your specific needs, whatever you're building.
+- **Parallel Asynchronous Awesomeness**: Handle requests in parallel, like a symphony of asynchronous harmony. 🎶
+
+## 📦 Installation
+
+Getting started with **Requests** is a breeze:
+1. Open your NuGet Package Manager.
+2. Search for "Shard.Requests"
+3. Install it. Voilà! 🎉
 
-You can install Requests by searching for "Requests" in the NuGet Package Manager.
  - [Nuget](https://www.nuget.org/packages/Shard.Requests)
  - [GitHub](https://github.com/TypNull/Requests)
 
 ## Usage
 
-To utilize the **Requests** library in C#, begin by importing it:
+To utilize the Requests library in C#, begin by importing it:
 
 ```csharp
 using Shard.Requests;
 ```
 
-Next, instantiate a `Request` object, and it will automatically be included in the `RequestHandler`. If a request encounters an error, the `RequestHandler` will automatically retry the request based on the specified retry settings. For additional information, refer to the Requests [Wiki](https://github.com/TypNull/Requests/wiki/).
+Next, instantiate a `Request` object, and it will automatically be included in the `RequestHandler`. If a request encounters an error, the `RequestHandler` will automatically retry the request based on the specified retry settings.
 
 ## Classes
 
@@ -39,11 +44,14 @@ This library includes the following classes:
 - **ProgressableContainer:** A container class to merge requests together that are using a `Progress` object to report the progress.
 - **RequestHandler:** A class to handle requests. Every handler is independent of any other handler.
 
-> Expand and use as you like!
+> Expand and use as you like!<br />
+> Because handling requests should be as delightful as a warm cup of cocoa on a winter day.
+
+ For additional information, refer to the Requests [Wiki](https://github.com/TypNull/Requests/wiki/).
 
 ## Examples
 
-Here is an example of creating a child class of `Request`, called `OwnRequest`:
+Meet our star, the `OwnRequest` class:
 
 ```cs
 public class OwnRequest : Request<RequestOptions<VoidStruct, VoidStruct>, VoidStruct, VoidStruct>
@@ -62,7 +70,8 @@ public class OwnRequest : Request<RequestOptions<VoidStruct, VoidStruct>, VoidSt
     }
 }
 ```
-To create an `OwnRequest`, use the following code:
+
+OwnRequest is a straightforward implementation of a child class of Request. It doesn’t overwhelm you with complexity, but it’s incredibly useful for quick implementations:
 
 ```cs
 // Create an object and pass as a parameter an action that uses a CancellationToken
@@ -82,10 +91,15 @@ new OwnRequest(async (token) =>
 });
 ```
 
-## Contributing
+Create your own requests with a sprinkle of magic! ✨
+
+## 🌟 Contributing
+
+Join our quest! If you'd like to contribute to this library, submit a pull request or open an issue. We appreciate your help in making **Requests** the best it can be!
 
-If you would like to contribute to this library, please submit a pull request or open an issue. We welcome all contributions and appreciate your help in making Requests the best library it can be!
+## 📜 License
 
-## License
+**Requests** is licensed under the MIT license. 
 
-Requests is licensed under the MIT license.
+## **Free Code** and **Free to Use**
+#### Have fun!

Requests/Channel/AsyncOperation.cs

@@ -39,7 +39,7 @@ private static void QueueUserWorkItem(Action<object?> action, object? state) =>
             Task.Factory.StartNew(action, state,
                 CancellationToken.None, TaskCreationOptions.DenyChildAttach, TaskScheduler.Default);
 
-        private static CancellationTokenRegistration UnsafeRegister(CancellationToken cancellationToken, Action<object?> action, object? state) =>
+        private static CancellationTokenRegistration UnsafeRegister(Action<object?> action, object? state, CancellationToken cancellationToken) =>
             cancellationToken.Register(action, state);
         /// <summary>Registration with a provided cancellation token.</summary>
         private readonly CancellationTokenRegistration _registration;
@@ -92,11 +92,11 @@ public AsyncOperation(bool runContinuationsAsynchronously, bool pooled = false,
             if (cancellationToken.CanBeCanceled)
             {
                 CancellationToken = cancellationToken;
-                _registration = UnsafeRegister(cancellationToken, static s =>
+                _registration = UnsafeRegister(static s =>
                 {
                     AsyncOperation<TResult> thisRef = (AsyncOperation<TResult>)s!;
                     thisRef.TrySetCanceled(thisRef.CancellationToken);
-                }, this);
+                }, this, cancellationToken);
             }
         }
 

Requests/Channel/ChannelUtilities.cs

@@ -2,17 +2,23 @@
 
 namespace Requests.Channel
 {
-    /// <summary>Provides internal helper methods for implementing channels.</summary>
+    /// <summary>
+    /// Provides helper methods for implementing channels.
+    /// </summary>
     internal static class ChannelUtilities
     {
-        /// <summary>Sentinel object used to indicate being done writing.</summary>
+        /// <summary>
+        /// A sentinel object used to indicate the completion of writing.
+        /// </summary>
         internal static readonly Exception s_doneWritingSentinel = new(nameof(s_doneWritingSentinel));
 
-        /// <summary>Completes the specified TaskCompletionSource.</summary>
-        /// <param name="tcs">The source to complete.</param>
+        /// <summary>
+        /// Completes the specified TaskCompletionSource.
+        /// </summary>
+        /// <param name="tcs">The TaskCompletionSource to complete.</param>
         /// <param name="error">
-        /// The optional exception with which to complete.
-        /// If this is null or the DoneWritingSentinel, the source will be completed successfully.
+        /// The optional exception to complete the TaskCompletionSource with.
+        /// If this is null or the DoneWritingSentinel, the TaskCompletionSource will be completed successfully.
         /// If this is an OperationCanceledException, it'll be completed with the exception's token.
         /// Otherwise, it'll be completed as faulted with the exception.
         /// </param>
@@ -26,10 +32,12 @@ internal static void Complete(TaskCompletionSource tcs, Exception? error = null)
                 tcs.TrySetResult();
         }
 
-        /// <summary>Gets a value task representing an error.</summary>
+        /// <summary>
+        /// Gets a ValueTask that represents an error.
+        /// </summary>
         /// <typeparam name="T">Specifies the type of the value that would have been returned.</typeparam>
-        /// <param name="error">The error.  This may be <see cref="s_doneWritingSentinel"/>.</param>
-        /// <returns>The failed task.</returns>
+        /// <param name="error">The error. This may be <see cref="s_doneWritingSentinel"/>.</param>
+        /// <returns>The failed ValueTask.</returns>
         internal static ValueTask<T> GetInvalidCompletionValueTask<T>(Exception error)
         {
             if (error == s_doneWritingSentinel)
@@ -39,11 +47,12 @@ internal static ValueTask<T> GetInvalidCompletionValueTask<T>(Exception error)
                 return new(error is OperationCanceledException oce ? Task.FromCanceled<T>(oce.CancellationToken.IsCancellationRequested ? oce.CancellationToken : new CancellationToken(true)) : Task.FromException<T>(CreateInvalidCompletionException(error)));
 
         }
+
         /// <summary>
-        /// Sets the Queue waite if it is null
+        /// Queues a waiter if it is null.
         /// </summary>
-        /// <param name="tail"></param>
-        /// <param name="waiter"></param>
+        /// <param name="tail">The tail of the queue.</param>
+        /// <param name="waiter">The waiter to queue.</param>
         internal static void QueueWaiter(ref AsyncOperation<bool>? tail, AsyncOperation<bool> waiter)
         {
             AsyncOperation<bool>? c = tail;
@@ -58,11 +67,11 @@ internal static void QueueWaiter(ref AsyncOperation<bool>? tail, AsyncOperation<
         }
 
         /// <summary>
-        /// Goes throu all asyncOperation waiters and sets the result
+        /// Iterates through all AsyncOperation waiters and sets the result.
         /// </summary>
-        /// <param name="listTail"></param>
-        /// <param name="result"></param>
-        /// <param name="error"></param>
+        /// <param name="listTail">The tail of the list.</param>
+        /// <param name="result">The result to set.</param>
+        /// <param name="error">The error to set, if any.</param>
         internal static void WakeUpWaiters(ref AsyncOperation<bool>? listTail, bool result, Exception? error = null)
         {
             AsyncOperation<bool>? tail = listTail;
@@ -82,16 +91,21 @@ internal static void WakeUpWaiters(ref AsyncOperation<bool>? listTail, bool resu
             }
         }
 
-        /// <summary>Removes all operations from the queue, failing each.</summary>
-        /// <param name="operations">The queue of operations to complete.</param>
-        /// <param name="error">The error with which to complete each operations.</param>
+        /// <summary>
+        /// Removes all operations from the queue and fails each one.
+        /// </summary>
+        /// <param name="operations">The queue of operations to be completed.</param>
+        /// <param name="error">The error to complete each operation with.</param>
         internal static void FailOperations<T, TInner>(Deque<T> operations, Exception error) where T : AsyncOperation<TInner>
         {
             while (!operations.IsEmpty)
                 operations.DequeueHead().TrySetException(error);
         }
 
-        /// <summary>Creates and returns an exception object to indicate that a channel has been closed.</summary>
+        /// <summary>
+        /// Creates and returns an exception to indicate that a channel has been closed.
+        /// </summary>
+        /// <param name="inner">Optional inner exception. If it's an OperationCanceledException, it's returned as is. If it's not null and not DoneWritingSentinel, a new ChannelClosedException is created with it. Otherwise, a new ChannelClosedException is created without an inner exception.</param>
         internal static Exception CreateInvalidCompletionException(Exception? inner = null) =>
             inner is OperationCanceledException ? inner :
             inner != null && inner != s_doneWritingSentinel ? new ChannelClosedException(inner) :

Requests/Channel/Deque.cs

@@ -3,19 +3,46 @@
     // Licensed to the .NET Foundation under one or more agreements.
     // The .NET Foundation licenses this file to you under the MIT license
 
-    /// <summary>Provides a double-ended queue data structure.</summary>
-    /// <typeparam name="T">Type of the data stored in the dequeue.</typeparam>
+    /// <summary>
+    /// Represents a double-ended queue (deque) data structure.
+    /// </summary>
+    /// <typeparam name="T">Specifies the type of elements in the deque.</typeparam>
     internal class Deque<T>
     {
+        /// <summary>
+        /// The array to hold the elements of the deque.
+        /// </summary>
         private T[] _array = Array.Empty<T>();
-        private int _head; // First valid element in the queue
-        private int _tail; // First open slot in the dequeue, unless the dequeue is full
-        private int _size; // Number of elements.
 
+        /// <summary>
+        /// The position of the first valid element in the deque.
+        /// </summary>
+        private int _head;
+
+        /// <summary>
+        /// The position of the first open slot in the deque, unless the deque is full.
+        /// </summary>
+        private int _tail;
+
+        /// <summary>
+        /// The number of elements in the deque.
+        /// </summary>
+        private int _size;
+
+        /// <summary>
+        /// Gets the number of elements contained in the <see cref="Deque{T}"/>.
+        /// </summary>
         public int Count => _size;
 
+        /// <summary>
+        /// Gets a value indicating whether the <see cref="Deque{T}"/> is empty.
+        /// </summary>
         public bool IsEmpty => _size == 0;
 
+        /// <summary>
+        /// Adds an item to the tail of the <see cref="Deque{T}"/>.
+        /// </summary>
+        /// <param name="item">The object to add to the <see cref="Deque{T}"/>.</param>
         public void EnqueueTail(T item)
         {
             if (_size == _array.Length)
@@ -27,6 +54,10 @@ public void EnqueueTail(T item)
             _size++;
         }
 
+        /// <summary>
+        /// Removes and returns the object at the head of the <see cref="Deque{T}"/>.
+        /// </summary>
+        /// <returns>The object that is removed from the head of the <see cref="Deque{T}"/>.</returns>
         public T DequeueHead()
         {
             T item = _array[_head];
@@ -38,9 +69,17 @@ public T DequeueHead()
 
             return item;
         }
-        public T PeekHead() => _array[_head];
 
+        /// <summary>
+        /// Returns the object at the head of the <see cref="Deque{T}"/> without removing it.
+        /// </summary>
+        /// <returns>The object at the head of the <see cref="Deque{T}"/>.</returns>
+        public T PeekHead() => _array[_head];
 
+        /// <summary>
+        /// Returns the object at the tail of the <see cref="Deque{T}"/> without removing it.
+        /// </summary>
+        /// <returns>The object at the tail of the <see cref="Deque{T}"/>.</returns>
         public T PeekTail()
         {
             int index = _tail - 1;
@@ -49,6 +88,10 @@ public T PeekTail()
             return _array[index];
         }
 
+        /// <summary>
+        /// Removes and returns the object at the tail of the <see cref="Deque{T}"/>.
+        /// </summary>
+        /// <returns>The object that is removed from the tail of the <see cref="Deque{T}"/>.</returns>
         public T DequeueTail()
         {
             if (--_tail == -1)
@@ -61,7 +104,11 @@ public T DequeueTail()
             return item;
         }
 
-        public IEnumerator<T> GetEnumerator() // meant for debug purposes only
+        /// <summary>
+        /// Returns an enumerator that iterates through the <see cref="Deque{T}"/>.
+        /// </summary>
+        /// <returns>An enumerator for the <see cref="Deque{T}"/>.</returns>
+        public IEnumerator<T> GetEnumerator()
         {
             int pos = _head;
             int count = _size;
@@ -72,6 +119,9 @@ public T DequeueTail()
             }
         }
 
+        /// <summary>
+        /// Increases the capacity of the <see cref="Deque{T}"/> to accommodate additional elements.
+        /// </summary>
         private void Grow()
         {
             const int MinimumGrow = 4;

Requests/Channel/ParallelChannelOptions.cs

@@ -1,30 +1,39 @@
 namespace Requests.Channel
 {
     /// <summary>
-    /// Stores options that configure the degree of max parallism in for the channel
+    /// Represents a configuration class for setting the maximum degree of parallelism in a channel.
     /// </summary>
     public class ParallelChannelOptions : ParallelOptions
     {
+        /// <summary>
+        /// The maximum degree of parallelism for the channel.
+        /// </summary>
         private int _maxDegreeOfParallelism = Environment.ProcessorCount;
 
         /// <summary>
-        /// Event that notifys the changed degree of parallelism
+        /// Occurs when the maximum degree of parallelism changes.
         /// </summary>
         public event EventHandler<int>? DegreeOfParallelismChangedDelta;
 
         /// <summary>
-        /// Pause token
+        /// Gets or sets the pause token that can be used to easily end the process.
         /// </summary>
         public PauseToken EasyEndToken { get; set; }
 
         /// <summary>
-        /// Main contructor
+        /// Initializes a new instance of the <see cref="ParallelChannelOptions"/> class.
         /// </summary>
         public ParallelChannelOptions() => base.MaxDegreeOfParallelism = int.MaxValue;
 
         /// <summary>
-        /// Maximal degree of parallelism of the channel
+        /// Gets or sets the maximum degree of parallelism for the channel.
         /// </summary>
+        /// <value>
+        /// The maximum degree of parallelism.
+        /// </value>
+        /// <exception cref="ArgumentOutOfRangeException">
+        /// Thrown when the value is less than zero.
+        /// </exception>
         public new int MaxDegreeOfParallelism
         {
             get => _maxDegreeOfParallelism;