sockets: High-level network sockets

[ bsd3, library, network ] [ Propose Tags ]

This library provides a high-level abstraction for network sockets. It uses Haskell2010 (along with GADTs) without typeclasses to ensure that consumers of the API can only call appropriate functions on a socket.

Exceptions are tracked in the types of functions and returned to the caller with Either. The caller is free to handle these gracefully or to throw them. This library has another class of exceptions described as _unrecoverable_. This library only throws exceptions in three situations:

  • The library detects that it has misused the operating system's sockets API. This includes getting a sockaddr with an unexpected socket family. It also includes getting an error code that should not be possible. For example, the abstractions provided for both datagram sockets and stream sockets mean that send system calls in either context should never return the error code ENOTCONN. Consequently, this error is treated as unrecoverable.

  • The caller asks for a negatively-sized slice of a buffer (such exceptions indicate a mistake in the code consuming this API).

  • A system call fails with ENOBUFS or ENOMEM. These indicate that the operating system is out of memory. If this happens, the Out Of Memory (OOM) manager is likely killing processes to reclaim memory, so the process that received this message may be killed soon. Making things even worse is that the GHC runtime requests pages of memory from the operating system at times that are effectively unpredictable to Haskell developers. (Most memory-managed languages have this behavior). Any attempt to recover from ENOBUFS or ENOMEM might cause the runtime to allocate memory from the operating system. According to the documentation for the HeapOverflow exception, an allocation failure at this point in time (likely given the recent ENOBUFS/ENOMEM) would result in immidiate termination of the program. So, although it is technically possible to recover from ENOBUFS/ENOMEM, the OOM killer and the GHC runtime make it impossible to do so reliably. Consequently, these error codes are treated as fatal.

Modules

  • Socket
    • Socket.Address
    • Datagram
      • IPv4
        • Socket.Datagram.IPv4.Connected
        • Socket.Datagram.IPv4.Unconnected
      • Interruptible
        • Socket.Datagram.Interruptible.Addr
        • Socket.Datagram.Interruptible.ByteString
        • Socket.Datagram.Interruptible.Bytes
        • Socket.Datagram.Interruptible.MutableBytes
      • Socket.Datagram.Slab
      • Uninterruptible
        • Socket.Datagram.Uninterruptible.Addr
        • Socket.Datagram.Uninterruptible.ByteString
        • Socket.Datagram.Uninterruptible.Bytes
        • Socket.Datagram.Uninterruptible.MutableBytes
    • Stream
      • Socket.Stream.IPv4
      • Interruptible
        • Socket.Stream.Interruptible.Addr
        • Socket.Stream.Interruptible.ByteString
        • Socket.Stream.Interruptible.Bytes
        • Socket.Stream.Interruptible.Hybrid
        • Socket.Stream.Interruptible.MutableBytes
      • Uninterruptible
        • Socket.Stream.Uninterruptible.Addr
        • Socket.Stream.Uninterruptible.ByteString
        • Socket.Stream.Uninterruptible.Bytes
        • Socket.Stream.Uninterruptible.Hybrid
        • Socket.Stream.Uninterruptible.MutableBytes

Flags

Manual Flags

NameDescriptionDefault
mmsg

Use sendmmsg and recvmmsg

Disabled
verbose-errors

More informative messages from internal errors

Disabled
debug

Print debug output

Disabled
checked

Add bounds-checking to primitive array operations

Disabled
example

Build example executables

Disabled

Use -f <flag> to enable a flag, or -f -<flag> to disable that flag. More info

Downloads

Note: This package has metadata revisions in the cabal description newer than included in the tarball. To unpack the package including the revisions, use 'cabal get'.

Maintainer's Corner

For package maintainers and hackage trustees

Candidates

Versions [RSS] 0.1.0.0, 0.3.0.0, 0.3.1.0, 0.4.0.0, 0.5.0.0
Change log CHANGELOG.md
Dependencies base (>=4.11.1.0 && <5), byteslice (>=0.1.1 && <0.2), bytestring (>=0.10 && <0.11), error-codes (>=0.1.0.1 && <0.2), ip (>=1.4.1), posix-api (>=0.3.2 && <0.4), primitive (>=0.7 && <0.8), primitive-addr (>=0.1 && <0.2), primitive-offset (>=0.2 && <0.3), primitive-unlifted (>=0.1 && <0.2), sockets, stm (>=2.4), text (>=1.2) [details]
License BSD-3-Clause
Copyright 2019 Andrew Martin
Author Andrew Martin
Maintainer andrew.thaddeus@gmail.com
Revised Revision 1 made by andrewthad at 2019-07-21T20:09:43Z
Category Network
Home page https://github.com/andrewthad/sockets
Bug tracker https://github.com/andrewthad/sockets/issues
Uploaded by andrewthad at 2019-07-21T19:38:37Z
Distributions NixOS:0.5.0.0
Executables sockets-example
Downloads 1960 total (19 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs not available [build log]
All reported builds failed as of 2019-07-21 [all 3 reports]