Repository navigation
Document the purpose of Network.Socket.BSD or consider merging #201
Description
Activity
I'm a new maintainer. So, I don't know the historical reason. If we decide this change, I think that we should ask to
libraryML if this change is acceptable. In my opinion, the fewer modules, the better. :-)Relating to #169 where I proposed to provide
Safemodules.Reacted by Evan Rutledge BordenI agree with @kazu-yamamoto on the stance that the libraries mailing list should be consulted on matters like these. As well any removal should be passed through a proper deprecation cycle**.
On the subject raised by @mboes, I would propose more drastic action (if only as a thought experiment):
Networkhas long been deprecated, it should be removed.- If there is no valid case, after research, that
Network.Socket.BSDshould exist it should be merged and deprecated. Network.Socket's use ofStringis questionable. The existence of aStringbased socket implementation is mostly useless from a modern Haskell perspective. It has "training wheels" uses, but any serious networking application is going to utilizeByteString. These portions of the module should be deprecated and either removed or made a temporary alias to aNetwork.Socket.Stringmodule.
Again, these stances are aggressive and pie in the sky. This package is depended on by large swaths of the ecosystem and any change must be slow and thoughtful.
** I do not believe we have an official stance on deprecation. This is something for @kazu-yamamoto and I to consider and document.
To pile on, documentation in
Network.Socketexplicitly drive users away from itsStringimplementations:
Do not use the send and recv functions defined in this module in new code, as they incorrectly represent binary data as a Unicode string. As a result, these functions are inefficient and may lead to bugs in the program. Instead use the send and recv functions defined in the ByteString module.Yes. To deprecate something, we should prepare documentation and put them deprecated pragma first.
I support the deprecation of
NetworkandNetwork.Socket.BSD. I agree with @eborden's impression that theStringinterface inNetwork.Socketis questionable. However, I would like to keep them as is because the extent of the impact is too large and we should explain that users should useNetwork.Socket.ByteStringalways.@kazu-yamamoto, I agree that the scope of breakage from removing the string API is too large. Alternatively we could introduce warnings for those functions to further lead people in the right direction.
Excuse me for interrupting, i just come across here after trying to start use network, i almost get lost between these modules:
NetworkprovideconnectTowhich is the most obvious way to start a TCP connection, but it has wrong document Network documentation incorrectly claims handles are block-buffered #173 and you guys suggestNetworkis deprecated, so should i use it?Network.Socketprovidesocketwhich involve lots of details(AF_INET,Stream...), is there any plan to add helpers or should i use network-simple instead?- does functions in
Network.Socket.BSDworks on windows?
Another question maybe not related, is there any necessary to use
HandlerwithSocket(block-buffered or no buffered)? does os provide buffer already? I suggest someone add these knowledge to document.I get better understanding after reading many other language's net standard library and unix socket materials, now current module structure looks reasonable to me, here's what i think:
Networkis definitely not deprecated, it provide higher level abstraction, namelyconnectTo.- Although
Network.Socket.BSD's naming is confusing, it's cross platform, and provide uniform bsd style address resolution, it's better leave it be. - The
Stringapi inNetworkshould be marked deprecated indeed, there's no other usage than keeping compatibility. - We really shound add some helpers to
Networkmodule, for example:
-- we should be able to get connected 'Socket' and 'SockAddr' easily connectTo' :: HostName -> PortID -> IO (Socket, SockAddr)- Please merge code from package network-socket-options, it provide many useful socket option and cross-platform, and standard library in other languages usually support these operations. We can add these functions into
Network.Socketmodule or make a newNetwork.Socket.Extramodule.
@kazu-yamamoto What's your opinion on these change? do they make sense? should they go through core-library consensus?
These changes are readable to me.
Would you give us pull requests step by step?
If your pull request include too many commits, I would give up reviewing.Just like i said #211, many thoughts have changed since i'm getting more familiar with
networkand unix socket now, i'll try to improve the document situation first, but like unix socket itself, these low level operations are not easy to explain well.FYI, i have release tcp-streams for more high-level need, i think
networkhas done a good job already.@mboes What is your opinion at this moment?
I would like to close this issue. Please reopen if necessary.
The network package is really a combination of four API's:
Network, which is deprecated.Network.Socket, which is a set of straight up low-level bindings to the basic C socket API.Network.Socket.ByteString, morally the same thing but bytestring based.Network.Socket.BSD- I don't know.The latter provides additional functions not found in
Network.Socket, presumably specific to the "BSD" sockets API. But everything is the BSD sockets API. Even Winsock on Windows is just a (relatively minor for our purposes) extension of it. In fact many of the functions exported byNetwork.BSDare also exported when on the Windows platform. So is the split in two modules of the BSD sockets API a distinction without a difference?If so, I suggest we merge the two modules, for the sake of clarity. If not, then the purpose of
Network.Socket.BSDshould be clearly documented. It currently just says "defines Haskell bindings to network programming functionality provided by BSD Unix derivatives", which isn't too helpful given that the same could be said ofNetwork.Socket.