Add ItemDropped callback to ChannelOptionsBase (#76)

* Add `BufferItemDropped` callback to `ChannelOptionsBase`

* Add xmldocs to BufferItemDropped

* do not call BufferItemDropped for special `null` value

* small refactor so we can document why we wrap itemDropped

---------

Co-authored-by: Martijn Laarman <[email protected]>

Author: Prunkles

src/Elastic.Channels/BufferedChannelBase.cs

@@ -173,6 +173,13 @@ protected BufferedChannelBase(TChannelOptions options, ICollection<IChannelCallb
 				// DropWrite will make `TryWrite` always return true, which is not what we want.
 				FullMode = BoundedChannelFullMode.Wait
 			});
+
+		//we don't expose the fact TEvent is nullable to the consumer
+		Action<TEvent?>? itemDropped = options.BufferItemDropped is null ? null : e =>
+		{
+			if (e is not null)
+				options.BufferItemDropped?.Invoke(e);
+		};
 		InChannel = Channel.CreateBounded<TEvent?>(new BoundedChannelOptions(maxIn)
 		{
 			SingleReader = false,
@@ -183,7 +190,7 @@ protected BufferedChannelBase(TChannelOptions options, ICollection<IChannelCallb
 			// wait does not block it simply signals that Writer.TryWrite should return false and be retried
 			// DropWrite will make `TryWrite` always return true, which is not what we want.
 			FullMode = options.BufferOptions.BoundedChannelFullMode
-		});
+		}, itemDropped);
 
 		InboundBuffer = new InboundBuffer<TEvent>(BatchExportSize, BufferOptions.OutboundBufferMaxLifetime);
 

src/Elastic.Channels/ChannelOptionsBase.cs

@@ -20,6 +20,10 @@ public abstract class ChannelOptionsBase<TEvent, TResponse> : IChannelCallbacks<
 	/// <inheritdoc cref="BufferOptions"/>
 	public BufferOptions BufferOptions { get; set; } = new();
 
+	/// <summary>
+    /// Delegate that will be called when item is being dropped from channel. See <see cref="BufferOptions.BoundedChannelFullMode"/>.
+	/// </summary>
+	public Action<TEvent>? BufferItemDropped { get; set; }
 
 	/// <summary>
 	/// Ensures a <see cref="ChannelDiagnosticsListener{TEvent,TResponse}"/> gets registered so this <see cref="BufferedChannelBase{TChannelOptions,TEvent,TResponse}"/>