Documentation for routine close

Documentation for routine close, assembled from the following types:

class Channel

From Channel

(Channel) method close

Defined as:

method close(Channel:D:)

Close the Channel, normally. This makes subsequent send calls die with X::Channel::SendOnClosed. Subsequent calls of .receive may still drain any remaining items that were previously sent, but if the queue is empty, will throw an X::Channel::ReceiveOnClosed exception. A Seq produced by an @() or by the .list method will not terminate until this has been done.

my $c = Channel.new;
$c.close;
$c.send(1);
CATCH { default { put .^name''.Str } };
# OUTPUT: «X::Channel::SendOnClosed: Cannot send a message on a closed channel␤» 

Please note that any exception thrown may prevent .close from being called, this may hang the receiving thread. Use a LEAVE phaser to enforce the .close call in this case.

class IO::Handle

From IO::Handle

(IO::Handle) routine close

Defined as:

method close(IO::Handle:D: --> Bool:D)
multi sub close(IO::Handle $fh)

Closes an open file handle. It's not an error to call close on an already-closed filehandle. Returns True on success. If you close one of the standard file handles (by default: $*IN, $*OUT, or $*ERR), that is any handle with native-descriptor 2 or lower, you won't be able to re-open such a handle.

It's a common idiom to use LEAVE phaser for closing the handles, which ensures the handle is closed regardless of how the block is left.

if $do-stuff-with-the-file {
    my $fh = open "path-to-file";
    LEAVE close $fh;
    # ... do stuff with the file 
}
 
sub do-stuff-with-the-file (IO $path-to-file)
  my $fh = $path-to-file.open;
 
  # stick a `try` on it, since this will get run even when the sub is 
  # called with wrong arguments, in which case the `$fh` will be an `Any` 
  LEAVE try close $fh;
 
  # ... do stuff with the file 
}
 
given "foo/bar".IO.open(:w{
    .spurt: "I ♥ Perl 6!";
    .close;
}

Note: unlike some other languages, Perl 6 does not use reference counting, and so the file handles are NOT closed when they go out of scope. While they will get closed when garbage collected, garbage collection isn't guaranteed to get run. This means you must use an explicit close on handles opened for writing, to avoid data loss, and an explicit close is recommended on handles opened for reading as well, so that your program does not open too many files at the same time, triggering exceptions on further open calls.

Note several methods allow for providing :close argument, to close the handle after the operation invoked by the method completes. As a simpler alternative, the IO::Path type provides many reading and writing methods that let you work with files without dealing with file handles directly.

class IO::CatHandle

From IO::CatHandle

(IO::CatHandle) method close

Defined as:

method close(IO::CatHandle:D: --> True)

Closes the currently active source handle, as well as any already-open source handles, and empties the source handle queue. Unlike a regular IO::Handle, an explicit call to .close is often not necessary on a CatHandle, as merely exhausting all the input closes all the handles that need to be closed.

with IO::CatHandle.new: @bunch-of-handles {
    say .readchars: 42;
    .close# we are done; close all the open handles 
}

class IO::Pipe

From IO::Pipe

(IO::Pipe) method close

Defined as:

method close(IO::Pipe: --> Proc:D)

Closes the pipe and returns Proc object from which the pipe originates.

role IO::Socket

From IO::Socket

(IO::Socket) method close

method close(IO::Socket:D)

Closes the socket.

Fails if the socket is not connected.

class IO::Socket::Async

From IO::Socket::Async

(IO::Socket::Async) method close

method close()

Close the connected client IO::Socket::Async which will have been obtained from the listen Supply or the connect Promise.

In order to close the underlying listening socket created by listen you can close the Tap. See listen for examples.

class Tap

From Tap

(Tap) method close

method close(Tap:D:)

Closes the tap.