Enhance documentation for withLock method and improve Pool class logic for connection counting

Author: ArnabChatterjee20k

src/Pools/Adapter.php

@@ -17,7 +17,7 @@ abstract public function pop(int $timeout): mixed;
     abstract public function count(): int;
 
     /**
-     * Execute a callback with lock protection
+     * Execute a callback with lock protection if the adapter supports it
      *
      * @param callable $callback
      * @param int $timeout Timeout in seconds

src/Pools/Adapter/Stack.php

@@ -23,6 +23,10 @@ public function push(mixed $connection): static
         return $this;
     }
 
+    /**
+     * @param int $timeout Stack adapter will ignore timeout
+     * @return mixed
+     */
     public function pop(int $timeout): mixed
     {
         return array_pop($this->pool);
@@ -33,6 +37,12 @@ public function count(): int
         return count($this->pool);
     }
 
+    /**
+     * No lock applied and just the callback is executed
+     * @param callable $callback
+     * @param int $timeout
+     * @return mixed
+     */
     public function withLock(callable $callback, int $timeout): mixed
     {
         return $callback();

src/Pools/Adapter/Swoole.php

@@ -45,6 +45,12 @@ public function count(): int
         return is_int($length) ? $length : 0;
     }
 
+    /**
+     * Executes the callback under a lock and releases it afterward.
+     * @param callable $callback
+     * @param int $timeout
+     * @return mixed
+     */
     public function withLock(callable $callback, int $timeout): mixed
     {
         // Acquire lock for thread-safe operations with timeout to prevent deadlock

src/Pools/Pool.php

@@ -419,7 +419,7 @@ public function destroy(?Connection $connection = null): static
      */
     public function isEmpty(): bool
     {
-        return $this->pool->count() === 0;
+        return $this->count() === 0;
     }
 
     /**
@@ -440,6 +440,6 @@ private function recordPoolTelemetry(): void
         $this->telemetryActiveConnections->record($activeConnections, $this->telemetryAttributes);
         $this->telemetryIdleConnections->record($idleConnections, $this->telemetryAttributes);
         $this->telemetryOpenConnections->record($openConnections, $this->telemetryAttributes);
-        $this->telemetryPoolCapacity->record($activeConnections + $this->pool->count(), $this->telemetryAttributes);
+        $this->telemetryPoolCapacity->record($this->connectionsCreated, $this->telemetryAttributes);
     }
 }