Add EventLoopGlobalHook - a new global hook implementation

Author: TolikPylypchuk

SharpHook.Tests/EventLoopGlobalHookTests.cs

@@ -82,6 +82,8 @@ public void Run()
         this.ThrowIfRunning();
         this.ThrowIfDisposed();
 
+        this.BeforeRun();
+
         UioHookResult result;
 
         try
@@ -121,6 +123,8 @@ public Task RunAsync()
         this.ThrowIfRunning();
         this.ThrowIfDisposed();
 
+        this.BeforeRun();
+
         var source = new TaskCompletionSource<object?>();
 
         var thread = new Thread(() =>
@@ -180,6 +184,8 @@ public void Stop()
                 throw new HookException(result, this.FormatStopFailureMessage(result));
             }
         }
+
+        this.AfterStop();
     }
 
     /// <summary>
@@ -192,6 +198,11 @@ public void Stop()
     /// </remarks>
     public void Dispose()
     {
+        if (this.IsDisposed)
+        {
+            return;
+        }
+
         this.Dispose(true);
         GC.SuppressFinalize(this);
     }
@@ -203,7 +214,24 @@ public void Dispose()
     protected abstract void HandleHookEvent(ref UioHookEvent e);
 
     /// <summary>
-    /// Disposes of the global hook, stopping it if it is running.
+    /// Defines actions to be done before the global hook is started. The default implementation does nothing, but
+    /// it may change in a future version, so calling <see cref="BasicGlobalHookBase.BeforeRun" /> in an overriden
+    /// method is recommended.
+    /// </summary>
+    protected virtual void BeforeRun()
+    { }
+
+    /// <summary>
+    /// Defines actions to be done after the global hook is stopped. The default implementation does nothing, but
+    /// it may change in a future version, so calling <see cref="BasicGlobalHookBase.BeforeRun" /> in an overriden
+    /// method is recommended.
+    /// </summary>
+    protected virtual void AfterStop()
+    { }
+
+    /// <summary>
+    /// Disposes of the global hook, stopping it if it is running. This method will not be called if the global hook is
+    /// already disposed.
     /// </summary>
     /// <param name="disposing">
     /// <see langword="true" /> if the method is called from the <see cref="Dispose()" /> method.
@@ -212,11 +240,6 @@ public void Dispose()
     /// <exception cref="HookException">Stopping the hook has failed.</exception>
     protected virtual void Dispose(bool disposing)
     {
-        if (this.IsDisposed)
-        {
-            return;
-        }
-
         this.IsDisposed = true;
 
         if (this.IsRunning)

SharpHook/BasicGlobalHookBase.cs

@@ -0,0 +1,124 @@
+using System.Collections.Concurrent;
+
+namespace SharpHook;
+
+/// <summary>
+/// Represents an implementation of <see cref="IGlobalHook" /> which dispatches events to an event loop running on a
+/// separate dedicated thread.
+/// </summary>
+/// <remarks>
+/// <para>
+/// The event handlers will run on a separate thread. This way the hook itself will not be blocked if the handlers are
+/// long-running. The exception is the <see cref="IGlobalHook.HookDisabled" /> event which will run on the same thread
+/// on which the hook itself is running since at that point it doesn't matter anymore that the hook is not blocked.
+/// </para>
+/// <para>
+/// Setting <see cref="HookEventArgs.SuppressEvent" /> inside the handlers will have no effect as they are run
+/// on another thread.
+/// </para>
+/// </remarks>
+/// <seealso cref="IGlobalHook" />
+/// <seealso cref="GlobalHookBase" />
+/// <seealso cref="SimpleGlobalHook" />
+/// <seealso cref="TaskPoolGlobalHook" />
+public sealed class EventLoopGlobalHook : GlobalHookBase
+{
+#if NET9_0_OR_GREATER
+    private readonly Lock syncRoot = new();
+#else
+    private readonly object syncRoot = new();
+#endif
+
+    private readonly BlockingCollection<UioHookEvent> eventLoop = [];
+    private bool eventLoopStarted = false;
+
+    /// <summary>
+    /// Initializes a new instance of <see cref="EventLoopGlobalHook" />.
+    /// </summary>
+    /// <param name="globalHookType">The global hook type.</param>
+    /// <param name="globalHookProvider">
+    /// The underlying global hook provider, or <see langword="null" /> to use the default one.
+    /// </param>
+    /// <param name="runAsyncOnBackgroundThread">
+    /// <see langword="true" /> if <see cref="IBasicGlobalHook.RunAsync" /> should run the hook on a background thread.
+    /// Otherwise, <see langword="false" />.
+    /// </param>
+    [SuppressMessage(
+        "Style", "IDE0290:Use primary constructor", Justification = "Primary constructors don't support XML comments")]
+    public EventLoopGlobalHook(
+        GlobalHookType globalHookType = GlobalHookType.All,
+        IGlobalHookProvider? globalHookProvider = null,
+        bool runAsyncOnBackgroundThread = false)
+        : base(globalHookType, globalHookProvider, runAsyncOnBackgroundThread)
+    { }
+
+    /// <summary>
+    /// Starts the event loop.
+    /// </summary>
+    protected override void BeforeRun()
+    {
+        if (!this.eventLoopStarted)
+        {
+            lock (this.syncRoot)
+            {
+                if (!this.eventLoopStarted)
+                {
+                    new Thread(this.RunEventLoop).Start();
+                    this.eventLoopStarted = true;
+                }
+            }
+        }
+    }
+
+    /// <summary>
+    /// Handles the hook event.
+    /// </summary>
+    /// <param name="e">The event to handle.</param>
+    protected override void HandleHookEvent(ref UioHookEvent e)
+    {
+        if (!this.ShouldDispatchEvent(ref e))
+        {
+            return;
+        }
+
+        if (e.Type != EventType.HookDisabled)
+        {
+            this.eventLoop.Add(e);
+        } else
+        {
+            this.DispatchEvent(ref e);
+        }
+    }
+
+    /// <summary>
+    /// Disposes of the global hook, stopping it if it is running, and completing the event loop.
+    /// </summary>
+    /// <param name="disposing">
+    /// <see langword="true" /> if the method is called from the <see cref="BasicGlobalHookBase.Dispose()" /> method.
+    /// Otherwise, <see langword="false" />.
+    /// </param>
+    /// <exception cref="HookException">Stopping the hook has failed.</exception>
+    protected override void Dispose(bool disposing)
+    {
+        lock (this.syncRoot)
+        {
+            this.eventLoop.CompleteAdding();
+        }
+
+        base.Dispose(disposing);
+    }
+
+    private void RunEventLoop()
+    {
+        foreach (var @event in this.eventLoop.GetConsumingEnumerable())
+        {
+            var e = @event;
+            this.DispatchEvent(ref e);
+        }
+
+        lock (this.syncRoot)
+        {
+            this.eventLoop.Dispose();
+        }
+    }
+}

SharpHook/EventLoopGlobalHook.cs

@@ -6,6 +6,7 @@ namespace SharpHook;
 /// </summary>
 /// <seealso cref="IGlobalHook" />
 /// <seealso cref="SimpleGlobalHook" />
+/// <seealso cref="EventLoopGlobalHook" />
 /// <seealso cref="TaskPoolGlobalHook" />
 /// <seealso cref="BasicGlobalHookBase" />
 public abstract class GlobalHookBase : BasicGlobalHookBase, IGlobalHook
@@ -36,7 +37,8 @@ protected GlobalHookBase(
     /// <param name="e">The event to handle.</param>
     /// <remarks>
     /// Derived classes should call <see cref="DispatchEvent(ref UioHookEvent)" /> inside this method to raise the
-    /// appropriate event.
+    /// appropriate event. They can also call <see cref="ShouldDispatchEvent(ref UioHookEvent)" /> to determine whether
+    /// to attempt dispatching the event at all.
     /// </remarks>
     protected override abstract void HandleHookEvent(ref UioHookEvent e);
 

SharpHook/GlobalHookBase.cs

@@ -43,15 +43,15 @@ libuiohook also provides functions to get various system properties. The corresp
 
 ### Global Hooks
 
-SharpHook provides the `IGlobalHook` interface along with two default implementations which you can use to control the
+SharpHook provides the `IGlobalHook` interface along with three default implementations which you can use to control the
 hook and subscribe to its events. Here's a basic usage example:
 
 ```c#
 using SharpHook;
 
 // ...
 
-var hook = new TaskPoolGlobalHook();
+var hook = new EventLoopGlobalHook();
 
 hook.HookEnabled += OnHookEnabled;     // EventHandler<HookEventArgs>
 hook.HookDisabled += OnHookDisabled;   // EventHandler<HookEventArgs>
@@ -98,15 +98,20 @@ a real difference only on Windows where there are two different global hooks –
 macOS and Linux, there is one hook for all events, and this simply enables filtering keyboard or mouse events out on
 these OSes.
 
-SharpHook provides two implementations of `IGlobalHook`:
+SharpHook provides three implementations of `IGlobalHook`:
 
 - `SharpHook.SimpleGlobalHook` runs all of its event handlers on the same thread on which the hook itself runs. This
 means that the handlers should generally be fast since they will block the hook from handling the events that follow if
 they run for too long.
 
+- `SharpHook.EventLoopGlobalHook` runs all of its event handlers on a separate dedicated thread. On backpressure it will
+queue the remaining events which means that the hook will be able to process all events. This implementation should be
+preferred to `SimpleGlobalHook` except for very simple use-cases. But it has a downside – suppressing event propagation
+will be ignored since event handlers are run on another thread.
+
 - `SharpHook.TaskPoolGlobalHook` runs all of its event handlers on other threads inside the default thread pool for
-tasks. The parallelism level of the handlers can be configured. On backpressure it will queue the remaining handlers.
-This means that the hook will be able to process all events. This implementation should be preferred to
+tasks. The parallelism level of the handlers can be configured. On backpressure it will queue the remaining events which
+means that the hook will be able to process all events. This implementation should be preferred to
 `SimpleGlobalHook` except for very simple use-cases. But it has a downside – suppressing event propagation will be
 ignored since event handlers are run on other threads.