Module documentation for 0.6.1.0
This library aims to expose a minimal and cross platform interface for POSIX compliant networking code.
Every operation and every flag exposed should be supported with same semantics on every platform. If this cannot be guaranteed it should be supplied by another (extension) package.
Absolutely no conditional exports.
#ifdefmadness in the Haskell sources. The Haskell binding code uses the FFI to reference platform dependant C functions for each operation. If a platform is not POSIX compliant (i.e. Windows) equivalent functionality is implemented by using whatever the platform specific building blocks are.
Platform is fully supported. Each commit and release is automatically tested with Travis CI and several versions of GHC.
Fully supported on Windows7 (maybe Vista) or higher :-)
GHC’s runtime system on Windows does not offer an event notification mechanism for sockets. The original network library suffers from this, too. For example, connection attempts are non-interruptible etc. The approach taken to circumvent this in this library is to poll the non-blocking sockets with increasing delay. This guarantees non-interruptability and fairness between different threads. It allows for decent throughput while also keeping CPU consumption on a moderate level if a socket has not seen events for a longer period of time (maximum of 1 second delay after 20 polling iterations). The only drawback is potentially reduced response time of your application. The good part: Heavy load (e.g. connection requests or incoming traffic) will reduce this problem. Eventually your accepting thread won’t wait at all if there are several connection requests queued.
This workaround may be removed if someone is willing to sacrifice to improve the IO manager on Windows.
Each release is manually tested on a Windows 10 virtual machine with the latest Haskell Platform (64bit).
Working, but not regularly tested.
Please report when it is no longer working on MacOS.
The project uses tasty for testing.
There are two test suites:
threaded which are using the same
code. Only difference is that one is compiled against GHC’s single threaded RTS
and the other against the multi-threaded one. Run
cabal test to run both
In order to see details and colored output you may also want to try
ghc --make test/test.hs && ./test/test
0.6.1.0 Lars Petersen [email protected] 2016-08-11
A potential race condition has been fixed (issue #18):
c_get_last_errorwas supposed to return the error code of the last operation (if any). On Linux et.al. it just returned
errnowhereas on Windows it wrapped a call to
WSAGetLastError. The problem was that the value of
WSAGetLastErroris only valid when sampled immediately after the failed call. This could not be easily guaranteed the way it was implemented: GHC’s RTS is potentially allowed to interrupt the thread between the failed call and the call to
c_get_last_error(although this is very unlikely when no memory allocation is necessary). The content of
errnomight have been reset of overridden by another thread. The solution for this is that all FFI calls now take a pointer with a reserved memory location (allocated on the stack, so it’s quite cheap) and the C functions immediately save the errno (if necessary). The
unsafe ccalls are guaranteed to be uninterruptible.
All tests have been ported to
tastyas previously proposed by Roman Cheplyaka.
connectoperation to use
getsockoptwith SO_ERROR to determine socket connection status / error code instead of issuing a second connection attempt (see issue #15). On Windows, the solution is a bit more difficult:
getsockoptreturn 0 unless the operation has either succeeded or failed. Unfortunately, there did not exist a mechanism to wait for this condition (GHC’s IO manager lacks this feature). This has been circumvented by calling
selectfor the socket with minimal timeout several times with an exponential back-off. Tests have been added to validate different aspects of this.
0.6.0.1 Lars Petersen [email protected] 2016-04-10
- Adapted the
AddrInfotest suite to not depend on specific name resolution features that aren’t available in a
chroot()environment (see issue #12).
0.6.0.0 Lars Petersen [email protected] 2016-03-26
- Improved and adapted documentation.
SetSocketOptionto one single type class
NameInfoinstead of a tuple.
- Added all theoretically possible
- The type class
GetNameInfohas been renamed to
- The type class
GetAddressInfohas been renamed to
- Removed operation
withConnectedSocketwithout replacement. It should not be part of this minimal library. Its code can be retrieved from the repository if needed.
- The operations
receiveAllare now exported through
System.Socket.Type.Streamand no longer trough the main module. They are very specific, solely stream-oriented and just wrappers around the basic operations. Such operations shouldn’t pollute the main module.
- Issue #10: Ben Gamari reported that the associated type
SocketAddressis not injective which would lead to compilation failure on GHC 8.* . This is fixed by using a data family instead.
0.5.3.0 Lars Petersen [email protected] 2015-08-09
- Added a test for
eOperationNotSupported(try to listen on a UDP socket).
- Niklas Hambüchen added
0.5.2.0 Lars Petersen [email protected] 2015-07-08
- Don’t set
sendTo. This implicit behaviour is a bad design decision. The implications of this change are rather limited. The behaviour/correctness of an application is only affected if it hooked SIGPIPE. GHC’s RTS by default ignores SIGPIPE since #1619. You’re still advised to adapt your applications to use
msgNoSignalexplicitly when writing on stream oriented sockets. Otherwise the RTS gets unnecessarily interrupted. This is harmless, but annoying and not desired when developing high-performance applications.
msgNoSignalas 0 if not available and documented this behaviour.
- Added new exception value
0.5.1.0 Lars Petersen [email protected] 2015-06-22
0.5.0.0 Lars Petersen [email protected] 2015-06-19
- Introduced newtypes
ScopeIdin Inet6 family.
- Renamed nearly everything in response to very constructive criticism by Bryan O’Sullivan. This is a breaking change (sorry about that). I felt this was the last chance to get this straight before the library gets widely adopted. Additional kudos to @ignorantone and @whatsthepoint.
- Issue #7: Typo in documentation of inaddrNONE and inaddrBROADCAST. Kudos to Michael Fox.
0.4.0.1 Lars Petersen [email protected] 2015-06-17
- tar-ball did not contain relevant source files.
0.4.0.0 Lars Petersen [email protected] 2015-06-16
- Changed semantics of
connectoperation. It now blocks until a connection has either has been established or failed.
- Added convenience operation
- Added new operation
- Added new socket option IPV6_V6ONLY.
- Removed untested socket option SO_ACCEPTCONN.
- Correctly defining AI_ flags on Windows (MinGW doesn’t although they are all well support on Vista or higher).
- Got all tests passing on Windows 7.
0.3.0.1 Lars Petersen [email protected] 2015-06-07
- Fixed documentation of eaiNONAME.
- Fixed typo in .cabal file in reference to cbits file.
0.3.0.0 Lars Petersen [email protected] 2015-06-07
NameInfoFlagsare now instances of
- Dropped all sendmsg/recvmsg related operations (harden the core first!)
- Dropped support for UNIX socket (will be separate package
- Renamed type function
- Added GetAddrInfo and GetNameInfo classes.
- Dropped support for SCTP (will be separate package
- Added support for RAW sockets.
- Started to support Windows (still unfinished).
- New operation
- ReceiveMsg now returns a strict
- New operations
- Restricted getAddrInfo and getNameInfo and added
- Added address family types INET, INET6 and UNIX (API breaking change)
- Fixed unsafeSend, unsafeSendTo and unsafeSendMsg (they were waiting for a read event instead of waiting for writing)
aiStrErrorvalues in Show instance
- Added constants for AddrInfoException
- Changed definitin of AddrInfoException
sendMsgoperation (+ some types and internals)
0.2.0.0 Lars Petersen [email protected] 2015-05-29
- Added a sendAll operation
- Exposed the Socket constructor
- Added msgWAITALL and fixed serious bug regarding all other MsgFlags
- Nicer Show instances for SockAddrIn and SockAddrIn6
- Hiding internal modules
0.1.0.1 Lars Petersen [email protected] 2015-05-28
- Added CHANGELOG.md
System.Socket.Unsafeto support older Preludes
0.1.0.0 Lars Petersen [email protected] 2015-05-28
- Initial release