Module crary_sock

Description
Data Types
Function Index
Function Details

Sock abstraction for HTTP.

Authors: Scott Parish (srp@srparish.net).

Description

Sock abstraction for HTTP. Provides an abstraction over a TCP socket to make it easy to write streaming/pipe-lining/etc HTTP servers

Data Types

timeout()

timeout() = Milliseconds | infinity

Milliseconds = integer()

Function Index

close/1	Close the socket, shutdown the reader and writer.
close_reader/1	Close the read half of the TCP socket.
done_reading/1	Indicate that the handler or controller is done reading.
done_writing/1	Indicate that the handler or controller is done writing.
new_resp/2	Used by a controller: return a new `sock()` for a new handler.
peer_name/1	Return the name of the socket's peer.
peer_port/1	Return the port of the socket's peer.
peername/1	Return the address and port of the socket's peer.
read/2	Return the next `Len` bytes read from `Sock`.
read/3	Return a binary of the next `Len` bytes read from `Sock`.
read_line/1	Return a string of the next line read from the socket.
read_line/2	Return a string of the next line read from the socket.
read_req_line/1	Read the request line from the socket.
read_req_line/2	Read the request line from the socket.
sockname/1	Return the address and port of the socket's local side.
start_link/4	Usually only called by crary_port to spawn/accept/process.
this_name/1	Return the name of the socket's local side.
this_port/1	Return the port of the socket's local side.
write/2	Write to the socket.
write_resp_line/2	Write the response line to the socket.
write_resp_line/3	Write the response line to the socket.

Function Details

close/1

close(Crary_req::sock() | crary:crary_req()) -> ok

throws {crary_sock, {error_closing_sock, R}}

Close the socket, shutdown the reader and writer.

Only call this if you really want to close the connection, otherwise this will terminate any futher pipe-lined requests.

close_reader/1

close_reader(Sock::sock() | crary:crary_req()) -> ok

throws {crary_sock, {error_closing_sock, Reason::term()}}

Close the read half of the TCP socket.

On hitting EOF when reading, we don't know if it was a full close() or a half duplex shutdown(), so close the reader, and add 'close' to the writers resp_q to finish shutting down when the last pipe-lined response has been written.

done_reading/1

done_reading(Sock::sock() | crary:crary_req()) -> ok

Indicate that the handler or controller is done reading.

This should be called whenever the handler or controller are done read/3ing for a particular request. Doing this right away allows the next pipe-lined request to start being handled.

done_writing/1

done_writing(Sock::sock() | crary:crary_req()) -> ok

Indicate that the handler or controller is done writing.

This should be called whenever the handler or controller are done write/2ing for a particular response. Doing this right away allows the next pipe-lined response to start being written.

new_resp/2

new_resp(Sock::sock() | crary:crary_req(), Mode) -> ok

Mode = wo | rw

Used by a controller: return a new sock() for a new handler.

This should be called to create a unique sock() for each handler to use. Basically this creates the references() used to identify when the handler should be allowed to read/3 as well as write/2

The mode wo should be used for requests such as GET where the handler will not need to read any body. rw should be used for requests such as PUT where the handler will be reading a body.

See also: crary_body:has_body/1.

peer_name/1

peer_name(Sock::sock() | crary:crary_req()) -> string()

throws {crary_sock, {peername_error, Reason::term()}}

Return the name of the socket's peer.

peer_port/1

peer_port(Sock::sock() | crary:crary_req()) -> integer()

throws {crary_sock, {peername_error, Reason::term()}}

Return the port of the socket's peer.

peername/1

peername(Sock::sock() | crary:crary_req()) -> {string(), integer()}

throws {crary_sock, {peername_error, Reason::term()}}

Return the address and port of the socket's peer.

read/2

read(Sock::sock() | crary:crary_req(), Len::integer()) -> binary()

throws {crary_sock, eof} | {crary_sock, {read_error, Reason::term()}}

Return the next Len bytes read from Sock.

See also: read/3.

read/3

read(Sock::sock() | crary:crary_req(), Len::integer(), Timeout::timeout()) -> binary()

throws {crary_sock, eof} | {crary_sock, timeout} | {crary_sock, {read_error, Reason::term()}}

Return a binary of the next Len bytes read from Sock.

Blocks until Len bytes are read. Use a Len of 0 to indicate blocking (if needed) until the next set of bytes are available and returning those regardless of size.