Copyright	(c) Dong Han 2018
License	BSD
Maintainer	winterland1989@gmail.com
Stability	experimental
Portability	non-portable
Safe Haskell	None
Language	Haskell2010

Z.IO.Network.UDP

Contents

TCP Client
Connected UDP Client
multicast and broadcast
Constants
- UDPFlag
- Membership

Description

This module provides an API for creating UDP sender and receiver.

Socket FD is created lazily if no local address is provided, that means various functions that need FD will throw bad FD exception if you initUDP with no local address e.g. setTTL.
If you want to create a socket FD but don't care about which port or interface you're using, use SocketAddrIPv4 portAny ipv4Any when initUDP.
Prefer recvUDPLoop because it can reuse receive buffer.

Synopsis

data UDP
initUDP :: UDPConfig -> Resource UDP
data UDPConfig = UDPConfig {
- udpSendMsgSize :: !Int
- udpLocalAddr :: Maybe (SocketAddr, UDPFlag)
}
defaultUDPConfig :: UDPConfig
sendUDP :: HasCallStack => UDP -> SocketAddr -> Bytes -> IO ()
data UDPRecvConfig = UDPRecvConfig {
- recvMsgSize :: !Int32
- recvBatchSize :: !Int
}
defaultUDPRecvConfig :: UDPRecvConfig
recvUDPLoop :: HasCallStack => UDPRecvConfig -> UDP -> ((Maybe SocketAddr, Bool, Bytes) -> IO a) -> IO ()
recvUDP :: HasCallStack => UDPRecvConfig -> UDP -> IO [(Maybe SocketAddr, Bool, Bytes)]
getSockName :: HasCallStack => UDP -> IO SocketAddr
data ConnectedUDP
connectUDP :: HasCallStack => UDP -> SocketAddr -> IO ConnectedUDP
disconnectUDP :: HasCallStack => ConnectedUDP -> IO UDP
getPeerName :: HasCallStack => ConnectedUDP -> IO SocketAddr
sendConnectedUDP :: HasCallStack => ConnectedUDP -> Bytes -> IO ()
setMembership :: HasCallStack => UDP -> CBytes -> CBytes -> Membership -> IO ()
setSourceMembership :: HasCallStack => UDP -> CBytes -> CBytes -> CBytes -> Membership -> IO ()
setMulticastLoop :: HasCallStack => UDP -> Bool -> IO ()
setMulticastTTL :: HasCallStack => UDP -> Int -> IO ()
setMulticastInterface :: HasCallStack => UDP -> CBytes -> IO ()
setBroadcast :: HasCallStack => UDP -> Bool -> IO ()
setTTL :: HasCallStack => UDP -> Int -> IO ()
type UDPFlag = CInt
pattern UDP_DEFAULT :: UDPFlag
pattern UDP_IPV6ONLY :: UDPFlag
pattern UDP_REUSEADDR :: UDPFlag
type Membership = CInt
pattern JOIN_GROUP :: Membership
pattern LEAVE_GROUP :: Membership

TCP Client

data UDP Source #

UDP socket.

UDP is not a sequential protocol, thus not an instance of 'Input/Output'. Message are received or sent individually, UDP socket is NOT thread safe! Use MVar UDP in multiple threads.

Instances

Instances details

Show UDP Source #
Instance details Defined in Z.IO.Network.UDP Methods showsPrec :: Int -> UDP -> ShowS # show :: UDP -> String # showList :: [UDP] -> ShowS #
Print UDP Source #
Instance details Defined in Z.IO.Network.UDP Methods toUTF8BuilderP :: Int -> UDP -> Builder () #

initUDP :: UDPConfig -> Resource UDP Source #

Initialize a UDP socket.

data UDPConfig Source #

UDP options.

Though technically message length field in the UDP header is a max of 65535, but large packets could be more likely dropped by routers, usually a packet(IPV4) with a payload <= 508 bytes is considered safe.

Constructors

UDPConfig
Fields udpSendMsgSize :: !Int maximum size of sending buffer udpLocalAddr :: Maybe (SocketAddr, UDPFlag) do we want bind a local address before receiving & sending? set to Nothing to let OS pick a random one.

Instances

Instances details

Eq UDPConfig Source #
Instance details Defined in Z.IO.Network.UDP Methods (==) :: UDPConfig -> UDPConfig -> Bool # (/=) :: UDPConfig -> UDPConfig -> Bool #
Ord UDPConfig Source #
Instance details Defined in Z.IO.Network.UDP Methods compare :: UDPConfig -> UDPConfig -> Ordering # (<) :: UDPConfig -> UDPConfig -> Bool # (<=) :: UDPConfig -> UDPConfig -> Bool # (>) :: UDPConfig -> UDPConfig -> Bool # (>=) :: UDPConfig -> UDPConfig -> Bool # max :: UDPConfig -> UDPConfig -> UDPConfig # min :: UDPConfig -> UDPConfig -> UDPConfig #
Show UDPConfig Source #
Instance details Defined in Z.IO.Network.UDP Methods showsPrec :: Int -> UDPConfig -> ShowS # show :: UDPConfig -> String # showList :: [UDPConfig] -> ShowS #
Generic UDPConfig Source #
Instance details Defined in Z.IO.Network.UDP Associated Types type Rep UDPConfig :: Type -> Type # Methods from :: UDPConfig -> Rep UDPConfig x # to :: Rep UDPConfig x -> UDPConfig #
JSON UDPConfig Source #
Instance details Defined in Z.IO.Network.UDP Methods fromValue :: Value -> Converter UDPConfig # toValue :: UDPConfig -> Value # encodeJSON :: UDPConfig -> Builder () #
Print UDPConfig Source #
Instance details Defined in Z.IO.Network.UDP Methods toUTF8BuilderP :: Int -> UDPConfig -> Builder () #
type Rep UDPConfig Source #
Instance details Defined in Z.IO.Network.UDP type Rep UDPConfig = D1 ('MetaData "UDPConfig" "Z.IO.Network.UDP" "Z-IO-0.6.1.0-gzKEsYtajW4dyRTMbokGF" 'False) (C1 ('MetaCons "UDPConfig" 'PrefixI 'True) (S1 ('MetaSel ('Just "udpSendMsgSize") 'SourceUnpack 'SourceStrict 'DecidedStrict) (Rec0 Int) :*: S1 ('MetaSel ('Just "udpLocalAddr") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Maybe (SocketAddr, UDPFlag)))))

defaultUDPConfig :: UDPConfig Source #

UDPConfig 512 Nothing

sendUDP :: HasCallStack => UDP -> SocketAddr -> Bytes -> IO () Source #

Send a UDP message to target address.

WARNING: A InvalidArgument with errno UV_EMSGSIZE will be thrown if message is larger than sendMsgSize.

data UDPRecvConfig Source #

Receiving buffering config.

Constructors

UDPRecvConfig
Fields recvMsgSize :: !Int32 maximum size of a received message recvBatchSize :: !Int how many messages we want to receive per uv loop, inside each uv_run, we do batch receiving, increase this number can improve receiving performance, at the cost of memory and potential GHC thread starving.

Instances

Instances details

Eq UDPRecvConfig Source #
Instance details Defined in Z.IO.Network.UDP Methods (==) :: UDPRecvConfig -> UDPRecvConfig -> Bool # (/=) :: UDPRecvConfig -> UDPRecvConfig -> Bool #
Ord UDPRecvConfig Source #
Instance details Defined in Z.IO.Network.UDP Methods compare :: UDPRecvConfig -> UDPRecvConfig -> Ordering # (<) :: UDPRecvConfig -> UDPRecvConfig -> Bool # (<=) :: UDPRecvConfig -> UDPRecvConfig -> Bool # (>) :: UDPRecvConfig -> UDPRecvConfig -> Bool # (>=) :: UDPRecvConfig -> UDPRecvConfig -> Bool # max :: UDPRecvConfig -> UDPRecvConfig -> UDPRecvConfig # min :: UDPRecvConfig -> UDPRecvConfig -> UDPRecvConfig #
Read UDPRecvConfig Source #
Instance details Defined in Z.IO.Network.UDP Methods readsPrec :: Int -> ReadS UDPRecvConfig # readList :: ReadS [UDPRecvConfig] # readPrec :: ReadPrec UDPRecvConfig # readListPrec :: ReadPrec [UDPRecvConfig] #
Show UDPRecvConfig Source #
Instance details Defined in Z.IO.Network.UDP Methods showsPrec :: Int -> UDPRecvConfig -> ShowS # show :: UDPRecvConfig -> String # showList :: [UDPRecvConfig] -> ShowS #
Generic UDPRecvConfig Source #
Instance details Defined in Z.IO.Network.UDP Associated Types type Rep UDPRecvConfig :: Type -> Type # Methods from :: UDPRecvConfig -> Rep UDPRecvConfig x # to :: Rep UDPRecvConfig x -> UDPRecvConfig #
JSON UDPRecvConfig Source #
Instance details Defined in Z.IO.Network.UDP Methods fromValue :: Value -> Converter UDPRecvConfig # toValue :: UDPRecvConfig -> Value # encodeJSON :: UDPRecvConfig -> Builder () #
Print UDPRecvConfig Source #
Instance details Defined in Z.IO.Network.UDP Methods toUTF8BuilderP :: Int -> UDPRecvConfig -> Builder () #
type Rep UDPRecvConfig Source #
Instance details Defined in Z.IO.Network.UDP type Rep UDPRecvConfig = D1 ('MetaData "UDPRecvConfig" "Z.IO.Network.UDP" "Z-IO-0.6.1.0-gzKEsYtajW4dyRTMbokGF" 'False) (C1 ('MetaCons "UDPRecvConfig" 'PrefixI 'True) (S1 ('MetaSel ('Just "recvMsgSize") 'SourceUnpack 'SourceStrict 'DecidedStrict) (Rec0 Int32) :*: S1 ('MetaSel ('Just "recvBatchSize") 'SourceUnpack 'SourceStrict 'DecidedStrict) (Rec0 Int)))

defaultUDPRecvConfig :: UDPRecvConfig Source #

UDPRecvConfig 512 6

recvUDPLoop :: HasCallStack => UDPRecvConfig -> UDP -> ((Maybe SocketAddr, Bool, Bytes) -> IO a) -> IO () Source #

Recv UDP message within a loop

Loop receiving can be faster since it can reuse receiving buffer. Unlike TCP server from Z.IO.Network.TCPserver, UDP worker function is called on current haskell thread instead of a forked one, if you have heavy computations to do within the worker function, consider using forkBa, or a producer-consumer architecture

recvUDP :: HasCallStack => UDPRecvConfig -> UDP -> IO [(Maybe SocketAddr, Bool, Bytes)] Source #

Recv messages from UDP socket, return source address if available, and a Bool to indicate if the message is partial (larger than receive buffer size).

getSockName :: HasCallStack => UDP -> IO SocketAddr Source #

Get the local IP and port of the UDP.

Connected UDP Client

data ConnectedUDP Source #

Wrapper for a connected UDP.

Instances

Instances details

Show ConnectedUDP Source #
Instance details Defined in Z.IO.Network.UDP Methods showsPrec :: Int -> ConnectedUDP -> ShowS # show :: ConnectedUDP -> String # showList :: [ConnectedUDP] -> ShowS #

connectUDP :: HasCallStack => UDP -> SocketAddr -> IO ConnectedUDP Source #

Associate the UDP handle to a remote address and port, so every message sent by this handle is automatically sent to that destination

disconnectUDP :: HasCallStack => ConnectedUDP -> IO UDP Source #

Disconnect the UDP handle from a remote address and port.

getPeerName :: HasCallStack => ConnectedUDP -> IO SocketAddr Source #

Get the remote IP and port on ConnectedUDP.

sendConnectedUDP :: HasCallStack => ConnectedUDP -> Bytes -> IO () Source #

Send a UDP message with a connected UDP.

WARNING: A InvalidArgument with errno UV_EMSGSIZE will be thrown if message is larger than sendMsgSize.

multicast and broadcast

setMembership Source #

Arguments

:: HasCallStack
=> UDP
-> CBytes	Multicast address to set membership for.
-> CBytes	Interface address.
-> Membership	UV_JOIN_GROUP \| UV_LEAVE_GROUP
-> IO ()

Set membership for a multicast group.

setSourceMembership Source #

Arguments

:: HasCallStack
=> UDP
-> CBytes	Multicast address to set membership for.
-> CBytes	Interface address.
-> CBytes	Source address.
-> Membership	UV_JOIN_GROUP \| UV_LEAVE_GROUP
-> IO ()