fix potential bug with blocking sockets
documentation and code refactoring