txt: ## dist_cpan-GARLANDG-IO-URing.md
  # NAME
  
  IO::URing - Access the io\_uring interface from Raku
  
  # SYNOPSIS
  
  Sample NOP call
  
  ```
  use IO::URing;
  
  my IO::URing $ring .= new(:8entries, :0flags);
  my $data = await $ring.nop(1);
  # or
  react whenever $ring.nop(1) -> $data {
      say "data: {$data.raku}";
    }
  }
  $ring.close; # free the ring
  
  ```
  
  # DESCRIPTION
  
  IO::URing is a binding to the new io\_uring interface in the Linux kernel.
  
  It will only work on Linux 5.6 and above. Use 5.10 or higher for best results. See the io\_uring documentation for which operations are supported on your kernel version.
  
  See the included IO::URing::Socket libraries for an example of IO::URing in action.
  
  Some knowledge of io\_uring and liburing is a pre-requisite for using this library. This code uses liburing to set up and submit requests to the ring.
  
  # IO::URing internal classes
  
  ## class IO::URing::Completion
  
  A Completion is returned from an awaited Handle. The completion contains the result of the operation.
  
  ### has Mu $.data
  
  The user data passed into the submission.
  
  ### has io\_uring\_sqe $.request
  
  The request passed into the IO::URing.
  
  ### has int $.result
  
  The result of the operation.
  
  ## class IO::URing::Handle
  
  A Handle is a Promise that can be used to cancel an IO::URing operation. Every call to submit or any non-prep operation will return a Handle.
  
  # IO::URing
  
  ## IO::URing methods
  
  ### method close
  
  ```
  method close() returns Mu
  
  ```
  
  Close the IO::URing object and shut down event processing.
  
  ### method features
  
  ```
  method features() returns Mu
  
  ```
  
  Get the enabled features on this IO::URing.
  
  ### method prep-nop
  
  ```
  method prep-nop(
      Int :$ioprio = 0,
      :$data,
      :$drain,
      :$link,
      :$hard-link,
      :$force-async
  ) returns IO::URing::Handle
  
  ```
  
  Prepare a no-op operation.
  
  ### method nop
  
  ```
  method nop(
      |c
  ) returns IO::URing::Handle
  
  ```
  
  Prepare and submit a no-op operation.
  
  ### multi method prep-readv
  
  ```
  multi method prep-readv(
      Int $fd,
      @bufs,
      Int :$offset = 0,
      :$data,
      Int :$ioprio = 0,
      :$drain,
      :$link,
      :$hard-link,
      :$force-async
  ) returns IO::URing::Handle
  
  ```
  
  Prepare a readv operation. A multi will handle a non-Int $fd by calling native-descriptor. A multi with a @bufs slurpy is provided.
  
  ### method readv
  
  ```
  method readv(
      |c
  ) returns IO::URing::Handle
  
  ```
  
  Prepare and submit a readv operation. See prep-readv for details.
  
  ### multi method prep-writev
  
  ```
  multi method prep-writev(
      Int $fd,
      @bufs,
      Int :$offset = 0,
      Int :$ioprio = 0,
      :$data,
      :$enc = "utf-8",
      :$drain,
      :$link,
      :$hard-link,
      :$force-async
  ) returns IO::URing::Handle
  
  ```
  
  Prepare a writev operation. A multi will handle a non-Int $fd by calling native-descriptor. A multi with a @bufs slurpy is provided.
  
  ### method writev
  
  ```
  method writev(
      |c
  ) returns IO::URing::Handle
  
  ```
  
  Prepare and submit a writev operation. See prep-writev for details.
  
  ### multi method prep-fsync
  
  ```
  multi method prep-fsync(
      Int $fd,
      Int $fsync-flags where { ... } = 0,
      Int :$ioprio = 0,
      :$data,
      :$drain,
      :$link,
      :$hard-link,
      :$force-async
  ) returns IO::URing::Handle
  
  ```
  
  Prepare an fsync operation. fsync-flags can be set to IORING\_FSYNC\_DATASYNC to use fdatasync(2) instead. Defaults to fsync(2).
  
  ### method fsync
  
  ```
  method fsync(
      $fd,
      Int $fsync-flags where { ... } = 0,
      :$data,
      :$drain,
      :$link,
      :$hard-link,
      :$force-async
  ) returns IO::URing::Handle
  
  ```
  
  Prepare and submit an fsync operation. See prep-fsync for details.
  
  ### multi method prep-poll-add
  
  ```
  multi method prep-poll-add(
      Int $fd,
      Int $poll-mask where { ... },
      Int :$ioprio = 0,
      :$data,
      :$drain,
      :$link,
      :$hard-link,
      :$force-async
  ) returns IO::URing::Handle
  
  ```
  
  Prepare a poll-add operation. A multi will handle a non-Int $fd by calling native-descriptor.
  
  ### method poll-add
  
  ```
  method poll-add(
      $fd,
      Int $poll-mask where { ... },
      :$data,
      :$drain,
      :$link,
      :$hard-link,
      :$force-async
  ) returns IO::URing::Handle
  
  ```
  
  Prepare and submit a poll-add operation. See prep-poll-add for details.
  
  ### method prep-poll-remove
  
  ```
  method prep-poll-remove(
      IO::URing::Handle $slot,
      Int :$ioprio = 0,
      :$data,
      :$drain,
      :$link,
      :$hard-link,
      :$force-async
  ) returns IO::URing::Handle
  
  ```
  
  Prepare a poll-remove operation. The provided Handle must be the Handle returned by the poll-add operation that should be cancelled.
  
  ### method poll-remove
  
  ```
  method poll-remove(
      IO::URing::Handle $slot,
      :$data,
      :$drain,
      :$link,
      :$hard-link,
      :$force-async
  ) returns IO::URing::Handle
  
  ```
  
  Prepare and submit a poll-remove operation.
  
  ### multi method prep-sendto
  
  ```
  multi method prep-sendto(
      Int $fd,
      Str $str,
      Int $union-flags,
      sockaddr_role $addr,
      Int $len,
      :$data,
      :$drain,
      :$link,
      :$hard-link,
      :$force-async,
      :$enc = "utf-8"
  ) returns IO::URing::Handle
  
  ```
  
  Prepare a sendmsg operation, mimicking sendto(2). A multi is provided that takes Blobs. A multi will handle a non-Int $fd by calling native-descriptor.
  
  ### multi method sendto
  
  ```
  multi method sendto(
      Int $fd,
      Blob $blob,
      Int $union-flags,
      sockaddr_role $addr,
      Int $len,
      :$data,
      :$drain,
      :$link,
      :$hard-link,
      :$force-async
  ) returns IO::URing::Handle
  
  ```
  
  Prepare and submit a sendmsg operation, mimicking sendto(2).
  
  ### multi method prep-sendmsg
  
  ```
  multi method prep-sendmsg(
      Int $fd,
      msghdr:D $msg,
      $union-flags,
      :$data,
      :$drain,
      :$link,
      :$hard-link,
      :$force-async
  ) returns IO::URing::Handle
  
  ```
  
  Prepare a sendmsg operation. A multi will handle a non-Int $fd by calling native-descriptor.
  
  ### method sendmsg
  
  ```
  method sendmsg(
      $fd,
      msghdr:D $msg,
      $flags,
      :$data,
      :$drain,
      :$link,
      :$hard-link,
      :$force-async
  ) returns IO::URing::Handle
  
  ```
  
  Prepare and submit a sendmsg operation.
  
  ### multi method prep-recvfrom
  
  ```
  multi method prep-recvfrom(
      Int $fd,
      Blob $buf,
      $flags,
      Blob $addr,
      :$data,
      :$drain,
      :$link,
      :$hard-link,
      :$force-async
  ) returns IO::URing::Handle
  
  ```
  
  Prepare a recvmsg operation, mimicking recvfrom(2). A multi is provided that takes Blobs. A multi will handle a non-Int $fd by calling native-descriptor.
  
  ### method recvfrom
  
  ```
  method recvfrom(
      $fd,
      Blob $buf,
      $flags,
      Blob $addr,
      :$data,
      :$drain,
      :$link,
      :$hard-link,
      :$force-async
  ) returns IO::URing::Handle
  
  ```
  
  Prepare and submit a recvmsg operation, mimicking recvfrom(2).
  
  ### multi method prep-recvmsg
  
  ```
  multi method prep-recvmsg(
      Int $fd,
      msghdr:D $msg is rw,
      $union-flags,
      :$data,
      :$drain,
      :$link,
      :$hard-link,
      :$force-async
  ) returns IO::URing::Handle
  
  ```
  
  Prepare a recvmsg operation. A multi will handle a non-Int $fd by calling native-descriptor.
  
  ### multi method recvmsg
  
  ```
  multi method recvmsg(
      Int $fd,
      msghdr:D $msg is rw,
      $flags,
      :$data,
      :$drain,
      :$link,
      :$hard-link,
      :$force-async
  ) returns IO::URing::Handle
  
  ```
  
  Prepare and submit a recvmsg operation
  
  ### method prep-cancel
  
  ```
  method prep-cancel(
      IO::URing::Handle $slot,
      Int $union-flags where { ... } = 0,
      :$data,
      :$drain,
      :$link,
      :$hard-link,
      :$force-async
  ) returns IO::URing::Handle
  
  ```
  
  Prepare a cancel operation to cancel a previously submitted operation. Note that this chases an in-flight operation, meaning it may or maybe not be successful in cancelling the operation. This means that both cases must be handled.
  
  ### method cancel
  
  ```
  method cancel(
      IO::URing::Handle $slot,
      Int :$flags where { ... } = 0,
      :$data,
      :$drain,
      :$link,
      :$hard-link,
      :$force-async
  ) returns IO::URing::Handle
  
  ```
  
  Prepare and submit a cancel operation
  
  ### multi method prep-accept
  
  ```
  multi method prep-accept(
      Int $fd,
      $sockaddr = Str,
      Int $union-flags = 0,
      :$data,
      :$drain,
      :$link,
      :$hard-link,
      :$force-async
  ) returns IO::URing::Handle
  
  ```
  
  Prepare an accept operation. A multi will handle a non-Int $fd by calling native-descriptor.
  
  ### method accept
  
  ```
  method accept(
      $fd,
      $sockaddr?,
      Int $union-flags = 0,
      :$data,
      :$drain,
      :$link,
      :$hard-link,
      :$force-async
  ) returns IO::URing::Handle
  
  ```
  
  Prepare and submit an accept operation.
  
  ### multi method prep-connect
  
  ```
  multi method prep-connect(
      Int $fd,
      sockaddr_role $sockaddr,
      :$data,
      :$drain,
      :$link,
      :$hard-link,
      :$force-async
  ) returns IO::URing::Handle
  
  ```
  
  Prepare a connect operation. A multi will handle a non-Int $fd by calling native-descriptor.
  
  ### method connect
  
  ```
  method connect(
      $fd,
      sockaddr_role $sockaddr,
      :$data,
      :$drain,
      :$link,
      :$hard-link,
      :$force-async
  ) returns IO::URing::Handle
  
  ```
  
  Prepare and submit a connect operation.
  
  ### multi method prep-send
  
  ```
  multi method prep-send(
      Int $fd,
      Blob $buf,
      $union-flags = 0,
      :$data,
      :$drain,
      :$link,
      :$hard-link,
      :$force-async
  ) returns IO::URing::Handle
  
  ```
  
  Prepare a send operation. A multi will handle a Str submission., which takes a named parameter :$enc = 'utf-8'. A multi will handle a non-Int $fd by calling native-descriptor.
  
  ### multi method send
  
  ```
  multi method send(
      $fd,
      $buf,
      Int $flags = 0,
      :$enc = "utf-8",
      :$data,
      :$drain,
      :$link,
      :$hard-link,
      :$force-async
  ) returns IO::URing::Handle
  
  ```
  
  Prepare and submit a send operation.
  
  ### multi method prep-recv
  
  ```
  multi method prep-recv(
      Int $fd,
      Blob $buf,
      Int $union-flags = 0,
      :$data,
      :$drain,
      :$link,
      :$hard-link,
      :$force-async
  ) returns IO::URing::Handle
  
  ```
  
  Prepare a recv operation. A multi will handle a non-Int $fd by calling native-descriptor.
  
  ### multi method recv
  
  ```
  multi method recv(
      $fd,
      Blob $buf,
      Int $union-flags = 0,
      :$data,
      :$drain,
      :$link,
      :$hard-link,
      :$force-async
  ) returns IO::URing::Handle
  
  ```
  
  Prepare and submit a recv operation.
  
  ### multi method prep-close-fd
  
  ```
  multi method prep-close-fd(
      Int $fd,
      :$data,
      :$drain,
      :$link,
      :$hard-link,
      :$force-async
  ) returns IO::URing::Handle
  
  ```
  
  Prepare a close operation. A multi will handle a non-Int $fd by calling native-descriptor.
  
  ### method close-fd
  
  ```
  method close-fd(
      Int $fd,
      :$data,
      :$drain,
      :$link,
      :$hard-link,
      :$force-async
  ) returns IO::URing::Handle
  
  ```
  
  Prepare and submit a close operation.
  
  ### multi method supported-ops
  
  ```
  multi method supported-ops() returns Hash
  
  ```
  
  Get the supported operations on an IO::URing instance.
  
  ### multi method supported-ops
  
  ```
  multi method supported-ops() returns Hash
  
  ```
  
  Get the supported operations without an IO::URing instance.
  
  # AUTHOR
  
  Travis Gibson [TGib.Travis@protonmail.com](mailto:TGib.Travis@protonmail.com)
  
  # COPYRIGHT AND LICENSE
  
  Copyright 2021 Travis Gibson
  
  This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.
  
  Some of the subs in this library were translated from liburing into Raku. Liburing is licensed under a dual LGPL and MIT license. Thank you Axboe for this library and interface.
  