chore(io): do not throw on non-blocking resource

docs/component/file.md

@@ -12,10 +12,10 @@
 
 #### `Functions`
 
-- [open_read_only](./../../src/Psl/File/open_read_only.php#L16)
-- [open_read_write](./../../src/Psl/File/open_read_write.php#L18)
-- [open_write_only](./../../src/Psl/File/open_write_only.php#L18)
-- [temporary](./../../src/Psl/File/temporary.php#L19)
+- [open_read_only](./../../src/Psl/File/open_read_only.php#L14)
+- [open_read_write](./../../src/Psl/File/open_read_write.php#L16)
+- [open_write_only](./../../src/Psl/File/open_write_only.php#L16)
+- [temporary](./../../src/Psl/File/temporary.php#L17)
 
 #### `Interfaces`
 

docs/component/io.md

@@ -15,7 +15,7 @@
 - [error_handle](./../../src/Psl/IO/error_handle.php#L17)
 - [input_handle](./../../src/Psl/IO/input_handle.php#L17)
 - [output_handle](./../../src/Psl/IO/output_handle.php#L17)
-- [pipe](./../../src/Psl/IO/pipe.php#L24)
+- [pipe](./../../src/Psl/IO/pipe.php#L22)
 
 #### `Interfaces`
 

docs/component/shell.md

@@ -14,6 +14,6 @@
 
 - [escape_argument](./../../src/Psl/Shell/escape_argument.php#L17)
 - [escape_command](./../../src/Psl/Shell/escape_command.php#L14)
-- [execute](./../../src/Psl/Shell/execute.php#L40)
+- [execute](./../../src/Psl/Shell/execute.php#L39)
 
 

src/Psl/File/Internal/ResourceHandle.php

@@ -31,8 +31,6 @@ final class ResourceHandle extends IO\Internal\ResourceHandle implements File\Re
 
     /**
      * @param resource|object $resource
-     *
-     * @throws Exception\BlockingException If unable to set the handle resource to non-blocking mode.
      */
     public function __construct(string $path, mixed $resource, bool $read, bool $write)
     {

src/Psl/File/Internal/open.php

@@ -11,8 +11,6 @@
  * @internal
  *
  * @codeCoverageIgnore
- *
- * @throws IO\Exception\BlockingException If unable to set the handle resource to non-blocking mode.
  */
 function open(string $filename, string $mode, bool $read, bool $write): ReadWriteHandleInterface
 {

src/Psl/File/ReadHandle.php

@@ -17,7 +17,6 @@ final class ReadHandle extends Internal\AbstractHandleWrapper implements ReadHan
     /**
      * @param resource|object $stream
      *
-     * @throws IO\Exception\BlockingException If unable to set the stream to non-blocking mode.
      * @throws Psl\Exception\InvariantViolationException If $path does not point to a file, or is not readable.
      */
     public function __construct(string $path)

src/Psl/File/ReadWriteHandle.php

@@ -18,7 +18,6 @@ final class ReadWriteHandle extends Internal\AbstractHandleWrapper implements Re
     /**
      * @param resource|object $stream
      *
-     * @throws IO\Exception\BlockingException If unable to set the stream to non-blocking mode.
      * @throws Psl\Exception\InvariantViolationException If $path points to a non-file node, or it not writeable.
      * @throws Filesystem\Exception\RuntimeException If unable to create $path when it does not exist.
      */

src/Psl/File/WriteHandle.php

@@ -17,7 +17,6 @@ final class WriteHandle extends Internal\AbstractHandleWrapper implements WriteH
     /**
      * @param resource|object $stream
      *
-     * @throws IO\Exception\BlockingException If unable to set the stream to non-blocking mode.
      * @throws Psl\Exception\InvariantViolationException If $filename points to a non-file node, or it not writeable.
      * @throws Filesystem\Exception\RuntimeException If unable to create $path when it does not exist.
      */

src/Psl/File/open_read_only.php

@@ -5,12 +5,10 @@
 namespace Psl\File;
 
 use Psl;
-use Psl\IO;
 
 /**
  * Open a file handle for read only.
  *
- * @throws IO\Exception\BlockingException If unable to set the stream to non-blocking mode.
  * @throws Psl\Exception\InvariantViolationException If $path does not point to a file, or is not readable. *
  */
 function open_read_only(string $path): ReadHandleInterface

src/Psl/File/open_read_write.php

@@ -6,12 +6,10 @@
 
 use Psl;
 use Psl\Filesystem;
-use Psl\IO;
 
 /**
  * Open a file handle for read and write.
  *
- * @throws IO\Exception\BlockingException If unable to set the stream to non-blocking mode.
  * @throws Psl\Exception\InvariantViolationException If $path points to a non-file node, or it not writeable.
  * @throws Filesystem\Exception\RuntimeException If unable to create $path when it does not exist.
  */

src/Psl/File/open_write_only.php

@@ -6,12 +6,10 @@
 
 use Psl;
 use Psl\Filesystem;
-use Psl\IO;
 
 /**
  * Open a file handle for write only.
  *
- * @throws IO\Exception\BlockingException If unable to set the stream to non-blocking mode.
  * @throws Psl\Exception\InvariantViolationException If $filename points to a non-file node, or it not writeable.
  * @throws Filesystem\Exception\RuntimeException If unable to create $path when it does not exist.
  */

src/Psl/File/temporary.php

@@ -6,15 +6,13 @@
 
 use Psl;
 use Psl\Filesystem;
-use Psl\IO;
 
 /**
  * Create a temporary file and open it for read and write.
  *
  * @throws Psl\Exception\InvariantViolationException If $directory doesn't exist or is not writable.
  * @throws Psl\Exception\InvariantViolationException If $prefix contains a directory separator.
  * @throws Filesystem\Exception\RuntimeException If unable to create the file.
- * @throws IO\Exception\BlockingException If unable to set the handle to non-blocking mode.
  */
 function temporary(?string $directory = null, ?string $prefix = null): ReadWriteHandleInterface
 {

src/Psl/IO/Internal/ResourceHandle.php

@@ -58,8 +58,6 @@ class ResourceHandle implements IO\CloseSeekReadWriteHandleInterface
 
     /**
      * @param resource|object $resource
-     *
-     * @throws Exception\BlockingException If unable to set the handle resource to non-blocking mode.
      */
     public function __construct(mixed $resource, bool $read, bool $write, bool $seek)
     {
@@ -70,17 +68,10 @@ public function __construct(mixed $resource, bool $read, bool $write, bool $seek
 
         /** @psalm-suppress UnusedFunctionCall */
         stream_set_read_buffer($resource, 0);
-        $result = stream_set_blocking($resource, false);
-        if ($result === false) {
-            $error = error_get_last();
-
-            throw new Exception\BlockingException(
-                $error['message'] ?? 'Unable to set the handle resource to non-blocking mode'
-            );
-        }
+        stream_set_blocking($resource, false);
 
         $meta = stream_get_meta_data($resource);
-        $this->blocks = ($meta['wrapper_type'] ?? '') === 'plainfile';
+        $this->blocks = $meta['blocked'] || ($meta['wrapper_type'] ?? '') === 'plainfile';
         if ($seek) {
             $seekable = (bool)$meta['seekable'];
 

src/Psl/IO/Reader.php

@@ -32,7 +32,6 @@ public function __construct(ReadHandleInterface $handle)
      * @param int $size The number of bytes to read.
      *
      * @throws Exception\AlreadyClosedException If the handle has been already closed.
-     * @throws Exception\BlockingException If the handle is a socket or similar, and the read would block.
      * @throws Exception\RuntimeException If an error occurred during the operation,
      *                                    or reached end of file before requested size.
      * @throws InvariantViolationException If $size is not positive.
@@ -79,7 +78,6 @@ function (): void {
 
     /**
      * @throws Exception\AlreadyClosedException If the handle has been already closed.
-     * @throws Exception\BlockingException If the handle is a socket or similar, and the read would block.
      * @throws Exception\RuntimeException If an error occurred during the operation.
      * @throws Exception\TimeoutException If $timeout is reached before being able to read from the handle.
      */
@@ -97,7 +95,6 @@ private function fillBuffer(?int $desired_bytes, ?float $timeout): void
      * Read a single byte from the handle.
      *
      * @throws Exception\AlreadyClosedException If the handle has been already closed.
-     * @throws Exception\BlockingException If the handle is a socket or similar, and the read would block.
      * @throws Exception\RuntimeException If an error occurred during the operation, or reached end of file.
      * @throws Psl\Exception\InvariantViolationException If $timeout is negative.
      */
@@ -138,7 +135,6 @@ public function readByte(?float $timeout = null): string
      *  or null if the end of file is reached before finding the current line terminator.
      *
      * @throws Exception\AlreadyClosedException If the handle has been already closed.
-     * @throws Exception\BlockingException If the handle is a socket or similar, and the read would block.
      * @throws Exception\RuntimeException If an error occurred during the operation.
      */
     public function readLine(): ?string
@@ -163,7 +159,6 @@ public function readLine(): ?string
      * data.
      *
      * @throws Exception\AlreadyClosedException If the handle has been already closed.
-     * @throws Exception\BlockingException If the handle is a socket or similar, and the read would block.
      * @throws Exception\RuntimeException If an error occurred during the operation.
      *
      * @psalm-suppress MissingThrowsDocblock
@@ -206,7 +201,6 @@ public function readUntil(string $suffix): ?string
      * @throws Exception\TimeoutException If $timeout is reached before being able to read from the handle.
      * @throws InvariantViolationException If $max_bytes is 0.
      * @throws Exception\AlreadyClosedException If the handle has been already closed.
-     * @throws Exception\BlockingException If the handle is a socket or similar, and the read would block.
      *
      * @return string the read data on success, or an empty string if the end of file is reached.
      *
@@ -242,7 +236,6 @@ public function read(?int $max_bytes = null, ?float $timeout = null): string
      * @throws Exception\RuntimeException If an error occurred during the operation.
      * @throws InvariantViolationException If $max_bytes is 0.
      * @throws Exception\AlreadyClosedException If the handle has been already closed.
-     * @throws Exception\BlockingException If the handle is a socket or similar, and the read would block.
      *
      * @return string the read data on success, or an empty string if the end of file is reached.
      *
@@ -289,7 +282,6 @@ public function getHandle(): ReadHandleInterface
     /**
      * @throws Exception\RuntimeException If an error occurred during the operation.
      * @throws Exception\AlreadyClosedException If the handle has been already closed.
-     * @throws Exception\BlockingException If the handle is a socket or similar, and the read would block.
      *
      * @return bool true if EOL has been reached, false otherwise.
      */
@@ -313,8 +305,6 @@ public function isEndOfFile(): bool
                 $this->eof = true;
                 return true;
             }
-        } catch (Exception\BlockingException) {
-            return false;
         } catch (Exception\ExceptionInterface) {
             // ignore; it'll be thrown again when attempting a real read.
         }

src/Psl/IO/Stream/CloseHandle.php

@@ -16,8 +16,6 @@ final class CloseHandle implements IO\CloseHandleInterface
 
     /**
      * @param resource|object $stream
-     *
-     * @throws IO\Exception\BlockingException If unable to set the stream to non-blocking mode.
      */
     public function __construct(mixed $stream)
     {

src/Psl/IO/Stream/CloseReadHandle.php

@@ -18,8 +18,6 @@ final class CloseReadHandle implements IO\CloseReadHandleInterface
 
     /**
      * @param resource|object $stream
-     *
-     * @throws IO\Exception\BlockingException If unable to set the stream to non-blocking mode.
      */
     public function __construct(mixed $stream)
     {

src/Psl/IO/Stream/CloseReadWriteHandle.php

@@ -19,8 +19,6 @@ final class CloseReadWriteHandle implements IO\CloseReadWriteHandleInterface
 
     /**
      * @param resource|object $stream
-     *
-     * @throws IO\Exception\BlockingException If unable to set the stream to non-blocking mode.
      */
     public function __construct(mixed $stream)
     {

src/Psl/IO/Stream/CloseSeekHandle.php

@@ -16,8 +16,6 @@ final class CloseSeekHandle implements IO\CloseSeekHandleInterface
 
     /**
      * @param resource|object $stream
-     *
-     * @throws IO\Exception\BlockingException If unable to set the stream to non-blocking mode.
      */
     public function __construct(mixed $stream)
     {

src/Psl/IO/Stream/CloseSeekReadHandle.php

@@ -18,8 +18,6 @@ final class CloseSeekReadHandle implements IO\CloseSeekReadHandleInterface
 
     /**
      * @param resource|object $stream
-     *
-     * @throws IO\Exception\BlockingException If unable to set the stream to non-blocking mode.
      */
     public function __construct(mixed $stream)
     {

src/Psl/IO/Stream/CloseSeekReadWriteHandle.php

@@ -19,8 +19,6 @@ final class CloseSeekReadWriteHandle implements IO\CloseSeekReadWriteHandleInter
 
     /**
      * @param resource|object $stream
-     *
-     * @throws IO\Exception\BlockingException If unable to set the stream to non-blocking mode.
      */
     public function __construct(mixed $stream)
     {

src/Psl/IO/Stream/CloseSeekWriteHandle.php

@@ -18,8 +18,6 @@ final class CloseSeekWriteHandle implements IO\CloseSeekWriteHandleInterface
 
     /**
      * @param resource|object $stream
-     *
-     * @throws IO\Exception\BlockingException If unable to set the stream to non-blocking mode.
      */
     public function __construct(mixed $stream)
     {

src/Psl/IO/Stream/CloseWriteHandle.php

@@ -18,8 +18,6 @@ final class CloseWriteHandle implements IO\CloseWriteHandleInterface
 
     /**
      * @param resource|object $stream
-     *
-     * @throws IO\Exception\BlockingException If unable to set the stream to non-blocking mode.
      */
     public function __construct(mixed $stream)
     {

src/Psl/IO/Stream/ReadHandle.php

@@ -18,8 +18,6 @@ final class ReadHandle implements IO\ReadHandleInterface
 
     /**
      * @param resource|object $stream
-     *
-     * @throws IO\Exception\BlockingException If unable to set the stream to non-blocking mode.
      */
     public function __construct(mixed $stream)
     {

src/Psl/IO/Stream/ReadWriteHandle.php

@@ -19,8 +19,6 @@ final class ReadWriteHandle implements IO\ReadWriteHandleInterface
 
     /**
      * @param resource|object $stream
-     *
-     * @throws IO\Exception\BlockingException If unable to set the stream to non-blocking mode.
      */
     public function __construct(mixed $stream)
     {

src/Psl/IO/Stream/SeekHandle.php

@@ -16,8 +16,6 @@ final class SeekHandle implements IO\SeekHandleInterface
 
     /**
      * @param resource|object $stream
-     *
-     * @throws IO\Exception\BlockingException If unable to set the stream to non-blocking mode.
      */
     public function __construct(mixed $stream)
     {

src/Psl/IO/Stream/SeekReadHandle.php

@@ -18,8 +18,6 @@ final class SeekReadHandle implements IO\SeekReadHandleInterface
 
     /**
      * @param resource|object $stream
-     *
-     * @throws IO\Exception\BlockingException If unable to set the stream to non-blocking mode.
      */
     public function __construct(mixed $stream)
     {

src/Psl/IO/Stream/SeekReadWriteHandle.php

@@ -19,8 +19,6 @@ final class SeekReadWriteHandle implements IO\SeekReadWriteHandleInterface
 
     /**
      * @param resource|object $stream
-     *
-     * @throws IO\Exception\BlockingException If unable to set the stream to non-blocking mode.
      */
     public function __construct(mixed $stream)
     {

src/Psl/IO/Stream/SeekWriteHandle.php

@@ -18,8 +18,6 @@ final class SeekWriteHandle implements IO\SeekWriteHandleInterface
 
     /**
      * @param resource|object $stream
-     *
-     * @throws IO\Exception\BlockingException If unable to set the stream to non-blocking mode.
      */
     public function __construct(mixed $stream)
     {

src/Psl/IO/Stream/WriteHandle.php

@@ -18,8 +18,6 @@ final class WriteHandle implements IO\WriteHandleInterface
 
     /**
      * @param resource|object $stream
-     *
-     * @throws IO\Exception\BlockingException If unable to set the stream to non-blocking mode.
      */
     public function __construct(mixed $stream)
     {

src/Psl/IO/WriteHandleConvenienceMethodsTrait.php

@@ -27,7 +27,6 @@ trait WriteHandleConvenienceMethodsTrait
      * do not want this to happen.
      *
      * @throws Exception\AlreadyClosedException If the handle has been already closed.
-     * @throws Exception\BlockingException If the handle is a socket or similar, and the write would block.
      * @throws Exception\RuntimeException If an error occurred during the operation.
      * @throws Exception\TimeoutException If reached timeout before completing the operation.
      */