diff options
Diffstat (limited to 'guide/connect.md')
-rw-r--r-- | guide/connect.md | 96 |
1 files changed, 0 insertions, 96 deletions
diff --git a/guide/connect.md b/guide/connect.md deleted file mode 100644 index 5655d66..0000000 --- a/guide/connect.md +++ /dev/null @@ -1,96 +0,0 @@ -Connection -========== - -This chapter describes how to open, monitor and close -a connection using the Gun client. - -Opening a new connection ------------------------- - -Gun is designed with the SPDY and Websocket protocols in mind, -and as such establishes a permanent connection to the remote -server. Because of this, the connection must be initiated -before being able to send any request. - -The process that creates the connection is also known as the -owner of the connection, or the controlling process.. Only -this process can perform operations on the connection, and -only this process will receive messages from the connection. - -To open a new connection, the `gun:open/{2,3}` function can be used. - -``` erlang -{ok, Pid} = gun:open("twitter.com", 443). -``` - -Gun will by default assume that SSL should be used. - -The connection is managed by a separate process and is supervised -by the Gun supervisor directly. - -The connection can later be stopped either gracefully or abruptly -by the client. If an unexpected disconnection occurs, the client -will retry connecting every few seconds until it succeeds and -can resume normal operations. - -Monitoring the connection process ---------------------------------- - -The connection is managed by a separate process. Because -software errors are a reality, it is important to monitor -this process for failure. Thankfully, due to the asynchronous -nature of Gun, we only need to create a monitor once when -the connection is established. - -``` erlang -{ok, Pid} = gun:open("twitter.com", 443). -MRef = monitor(process, Pid). -``` - -There is no need to monitor again after that regardless of -the number of requests sent or messages received. - -You can detect the process failure when receiving messages. - -``` erlang -receive - {'DOWN', Tag, _, _, Reason} -> - error_logger:error_msg("Oops!"), - exit(Reason); - %% Receive Gun messages here... -end. -``` - -You will probably want to reopen the connection when that -happens. - -Closing the connection abruptly -------------------------------- - -The connection can be stopped abruptly at any time by calling -the `gun:close/1` function. - -``` erlang -gun:close(Pid). -``` - -The process is stopped immediately. - -Closing the connection gracefully ---------------------------------- - -The connection can also be stopped gracefully by calling the -`gun:shutdown/1` function. - -``` erlang -gun:shutdown(Pid). -``` - -Gun will refuse any new requests from both the Erlang side and -the server and will attempt to finish the currently opened -streams. For example if you performed a GET request just before -calling `gun:shutdown/1`, you will still receive the response -before Gun closes the connection. - -If you set a monitor beforehand, it will inform you when the -connection has finally been shutdown. |