Fail when epoll transport is requested but unavailable

Rather than silently falling back to the NIO transport, client and
server constructors now throw an excpetion with info on how to fix the
problem when requesting to use the native epoll transport but no
implementation for the current platform is available on the classpath.

Author: DerGuteMoritz

src/aleph/http.clj

@@ -46,7 +46,7 @@
    | `max-initial-line-length` | the maximum characters that can be in the initial line of the request, defaults to `8192`
    | `max-header-size` | the maximum characters that can be in a single header entry of a request, defaults to `8192`
    | `max-chunk-size` | the maximum characters that can be in a single chunk of a streamed request, defaults to `16384`
-   | `epoll?` | if `true`, uses `epoll` when available, defaults to `false`
+   | `epoll?` | if `true`, uses `epoll`, defaults to `false`.
    | `compression?` | when `true` enables http compression, defaults to `false`
    | `compression-level` | optional compression level, `1` yields the fastest compression and `9` yields the best compression, defaults to `6`. When set, enables http content compression regardless of the `compression?` flag value
    | `idle-timeout` | when set, forces keep-alive connections to be closed after an idle time, in milliseconds
@@ -115,7 +115,7 @@
    | `response-buffer-size` | the amount of the response, in bytes, that is buffered before the request returns, defaults to `65536`.  This does *not* represent the maximum size response that the client can handle (which is unbounded), and is only a means of maximizing performance.
    | `keep-alive?` | if `true`, attempts to reuse connections for multiple requests, defaults to `true`.
    | `idle-timeout` | when set, forces keep-alive connections to be closed after an idle time, in milliseconds.
-   | `epoll?` | if `true`, uses `epoll` when available, defaults to `false`
+   | `epoll?` | if `true`, uses `epoll`, defaults to `false`
    | `raw-stream?` | if `true`, bodies of responses will not be buffered at all, and represented as Manifold streams of `io.netty.buffer.ByteBuf` objects rather than as an `InputStream`.  This will minimize copying, but means that care must be taken with Netty's buffer reference counting.  Only recommended for advanced users.
    | `max-initial-line-length` | the maximum length of the initial line (e.g. HTTP/1.0 200 OK), defaults to `65536`
    | `max-header-size` | the maximum characters that can be in a single header entry of a response, defaults to `65536`
@@ -216,7 +216,7 @@
    | `max-frame-payload` | maximum allowable frame payload length, in bytes, defaults to `65536`.
    | `max-frame-size` | maximum aggregate message size, in bytes, defaults to `1048576`.
    | `bootstrap-transform` | an optional function that takes an `io.netty.bootstrap.Bootstrap` object and modifies it.
-   | `epoll?` | if `true`, uses `epoll` when available, defaults to `false`
+   | `epoll?` | if `true`, uses `epoll`, defaults to `false`
    | `heartbeats` | optional configuration to send Ping frames to the server periodically (if the connection is idle), configuration keys are `:send-after-idle` (in milliseconds), `:payload` (optional, empty frame by default) and `:timeout` (optional, to close the connection if Pong is not received after specified timeout)."
   ([url]
     (websocket-client url nil))

src/aleph/netty.clj

@@ -798,6 +798,13 @@
 (defn epoll-available? []
   (Epoll/isAvailable))
 
+(defn ensure-epoll-available! []
+  (when-let [cause (Epoll/unavailabilityCause)]
+    (throw (IllegalArgumentException. (str "Epoll transport requested but implementation not available. "
+                                           "See https://netty.io/wiki/native-transports.html on how to add the necessary "
+                                           "dependency for your platform.")
+                                      cause))))
+
 (defn get-default-event-loop-threads
   "Determines the default number of threads to use for a Netty EventLoopGroup.
    This mimics the default used by Netty as of version 4.1."
@@ -880,7 +887,7 @@ initialize an DnsAddressResolverGroup instance.
    | `decode-idn?` | set if domain / host names should be decoded to unicode when received, defaults to `true`
    | `recursion-desired?` | if set to `true`, the resolver sends a DNS query with the RD (recursion desired) flag set, defaults to `true`
    | `name-servers` | optional list of DNS server addresses, automatically discovered when not set (platform dependent)
-   | `epoll?` | if `true`, uses `epoll` when available, defaults to `false`"
+   | `epoll?` | if `true`, uses `epoll`, defaults to `false`"
   [{:keys [max-payload-size
            max-queries-per-resolve
            address-types
@@ -907,8 +914,10 @@ initialize an DnsAddressResolverGroup instance.
          decode-idn? true
          recursion-desired? true
          epoll? false}}]
+  (when epoll?
+    (ensure-epoll-available!))
   (let [^Class
-        channel-type (if (and epoll? (epoll-available?))
+        channel-type (if epoll?
                        EpollDatagramChannel
                        NioDatagramChannel)]
     (cond-> (doto (DnsNameResolverBuilder.)
@@ -965,8 +974,10 @@ initialize an DnsAddressResolverGroup instance.
     ^SocketAddress local-address
     epoll?
     name-resolver]
+   (when epoll?
+     (ensure-epoll-available!))
     (let [^Class
-          channel (if (and epoll? (epoll-available?))
+          channel (if epoll?
                     EpollSocketChannel
                     NioSocketChannel)
 
@@ -980,7 +991,7 @@ initialize an DnsAddressResolverGroup instance.
                                (pipeline-builder p))
                              pipeline-builder)]
       (try
-        (let [client-group (if (and epoll? (epoll-available?))
+        (let [client-group (if epoll?
                              @epoll-client-group
                              @nio-client-group)
               resolver' (when (some? name-resolver)
@@ -1013,25 +1024,27 @@ initialize an DnsAddressResolverGroup instance.
    on-close
    ^SocketAddress socket-address
    epoll?]
+  (when epoll?
+    (ensure-epoll-available!))
   (let [num-cores      (.availableProcessors (Runtime/getRuntime))
         num-threads    (* 2 num-cores)
         thread-factory (enumerating-thread-factory "aleph-netty-server-event-pool" false)
         closed?        (atom false)
 
         ^EventLoopGroup group
-        (if (and epoll? (epoll-available?))
+        (if epoll?
           (EpollEventLoopGroup. num-threads thread-factory)
           (NioEventLoopGroup. num-threads thread-factory))
 
         ^Class channel
-        (if (and epoll? (epoll-available?))
+        (if epoll?
           EpollServerSocketChannel
           NioServerSocketChannel)
 
         ;; todo(kachayev): this one should be reimplemented after
         ;;                 KQueue transport is merged into master
         transport
-        (if (and epoll? (epoll-available?)) :epoll :nio)
+        (if epoll? :epoll :nio)
 
         pipeline-builder
         (if ssl-context

src/aleph/udp.clj

@@ -34,15 +34,17 @@
    | `socket-address` | a `java.net.SocketAddress` specifying both the port and interface to bind to.
    | `broadcast?` | if true, all UDP datagrams are broadcast.
    | `bootstrap-transform` | a function which takes the Netty `Bootstrap` object, and makes any desired changes before it's bound to a socket.
-   | `raw-stream?` | if true, the `:message` within each packet will be `io.netty.buffer.ByteBuf` objects rather than byte-arrays.  This will minimize copying, but means that care must be taken with Netty's buffer reference counting.  Only recommended for advanced users."
+   | `raw-stream?` | if true, the `:message` within each packet will be `io.netty.buffer.ByteBuf` objects rather than byte-arrays.  This will minimize copying, but means that care must be taken with Netty's buffer reference counting.  Only recommended for advanced users.
+   | `epoll?` | if `true`, uses `epoll`, defaults to `false`"
   [{:keys [socket-address port broadcast? raw-stream? bootstrap-transform epoll?]
     :or {epoll? false
          broadcast? false
          raw-stream? false
          bootstrap-transform identity}}]
+  (when epoll?
+    (netty/ensure-epoll-available!))
   (let [in (atom nil)
         d (d/deferred)
-        epoll? (and epoll? (netty/epoll-available?))
         g (if epoll?
             @netty/epoll-client-group
             @netty/nio-client-group)