Added some comments.

This commit is contained in:
cheatfate 2018-05-23 00:03:13 +03:00
parent 898e3602bd
commit 874fe9b5fd
1 changed files with 39 additions and 13 deletions

View File

@ -18,21 +18,21 @@ else:
type type
VectorKind = enum VectorKind = enum
DataBuffer, # Simple buffer pointer/length DataBuffer, # Simple buffer pointer/length
DataFile # File handle for sendfile/TransmitFile DataFile # File handle for sendfile/TransmitFile
type type
StreamVector = object StreamVector = object
kind: VectorKind # Writer vector source kind kind: VectorKind # Writer vector source kind
buf: pointer # Writer buffer pointer buf: pointer # Writer buffer pointer
buflen: int # Writer buffer size buflen: int # Writer buffer size
offset: uint # Writer vector offset offset: uint # Writer vector offset
writer: Future[void] # Writer vector completion Future writer: Future[void] # Writer vector completion Future
TransportKind* {.pure.} = enum TransportKind* {.pure.} = enum
Socket, # Socket transport Socket, # Socket transport
Pipe, # Pipe transport Pipe, # Pipe transport
File # File transport File # File transport
type type
StreamTransport* = ref object of RootRef StreamTransport* = ref object of RootRef
@ -611,6 +611,7 @@ else:
proc connect*(address: TransportAddress, proc connect*(address: TransportAddress,
bufferSize = DefaultStreamBufferSize): Future[StreamTransport] = bufferSize = DefaultStreamBufferSize): Future[StreamTransport] =
## Connect to ``address`` and create new transport for this connection.
var var
saddr: Sockaddr_storage saddr: Sockaddr_storage
slen: SockLen slen: SockLen
@ -714,12 +715,12 @@ proc start*(server: SocketServer) =
server.actEvent.fire() server.actEvent.fire()
proc stop*(server: SocketServer) = proc stop*(server: SocketServer) =
## Stops ``server`` ## Stops ``server``.
server.action = Stop server.action = Stop
server.actEvent.fire() server.actEvent.fire()
proc pause*(server: SocketServer) = proc pause*(server: SocketServer) =
## Pause ``server`` ## Pause ``server``.
server.action = Pause server.action = Pause
server.actEvent.fire() server.actEvent.fire()
@ -739,6 +740,7 @@ proc createStreamServer*(host: TransportAddress,
backlog: int = 100, backlog: int = 100,
bufferSize: int = DefaultStreamBufferSize, bufferSize: int = DefaultStreamBufferSize,
udata: pointer = nil): StreamServer = udata: pointer = nil): StreamServer =
## Create new TCP server
var var
saddr: Sockaddr_storage saddr: Sockaddr_storage
slen: SockLen slen: SockLen
@ -789,6 +791,8 @@ proc createStreamServer*(host: TransportAddress,
proc write*(transp: StreamTransport, pbytes: pointer, proc write*(transp: StreamTransport, pbytes: pointer,
nbytes: int): Future[int] {.async.} = nbytes: int): Future[int] {.async.} =
## Write data from buffer ``pbytes`` with size ``nbytes`` to transport
## ``transp``.
checkClosed(transp) checkClosed(transp)
var waitFuture = newFuture[void]("transport.write") var waitFuture = newFuture[void]("transport.write")
var vector = StreamVector(kind: DataBuffer, writer: waitFuture, var vector = StreamVector(kind: DataBuffer, writer: waitFuture,
@ -804,6 +808,10 @@ proc write*(transp: StreamTransport, pbytes: pointer,
proc writeFile*(transp: StreamTransport, handle: int, proc writeFile*(transp: StreamTransport, handle: int,
offset: uint = 0, offset: uint = 0,
size: int = 0): Future[void] {.async.} = size: int = 0): Future[void] {.async.} =
## Write data from file descriptor ``handle`` to transport ``transp``.
##
## You can specify starting ``offset`` in opened file and number of bytes
## to transfer from file to transport via ``size``.
if transp.kind != TransportKind.Socket: if transp.kind != TransportKind.Socket:
raise newException(TransportError, "You can transmit files only to sockets") raise newException(TransportError, "You can transmit files only to sockets")
checkClosed(transp) checkClosed(transp)
@ -820,7 +828,11 @@ proc writeFile*(transp: StreamTransport, handle: int,
proc readExactly*(transp: StreamTransport, pbytes: pointer, proc readExactly*(transp: StreamTransport, pbytes: pointer,
nbytes: int) {.async.} = nbytes: int) {.async.} =
## Read exactly ``nbytes`` bytes from transport ``transp``. ## Read exactly ``nbytes`` bytes from transport ``transp`` and store it to
## ``pbytes``.
##
## If EOF is received and ``nbytes`` is not yet readed, the procedure
## will raise ``TransportIncompleteError``.
checkClosed(transp) checkClosed(transp)
checkPending(transp) checkPending(transp)
var index = 0 var index = 0
@ -880,6 +892,10 @@ proc readOnce*(transp: StreamTransport, pbytes: pointer,
proc readUntil*(transp: StreamTransport, pbytes: pointer, nbytes: int, proc readUntil*(transp: StreamTransport, pbytes: pointer, nbytes: int,
sep: seq[byte]): Future[int] {.async.} = sep: seq[byte]): Future[int] {.async.} =
## Read data from the transport ``transp`` until separator ``sep`` is found.
##
## On success, the data and separator will be removed from the internal
## buffer (consumed). Returned data will NOT include the separator at the end.
checkClosed(transp) checkClosed(transp)
checkPending(transp) checkPending(transp)
@ -931,6 +947,16 @@ proc readUntil*(transp: StreamTransport, pbytes: pointer, nbytes: int,
proc readLine*(transp: StreamTransport, limit = 0, proc readLine*(transp: StreamTransport, limit = 0,
sep = "\r\n"): Future[string] {.async.} = sep = "\r\n"): Future[string] {.async.} =
## Read one line from transport ``transp``, where "line" is a sequence of
## bytes ending with ``sep`` (default is "\r\n").
##
## If EOF is received, and ``sep`` was not found, the method will return the
## partial read bytes.
##
## If the EOF was received and the internal buffer is empty, return an
## empty string.
##
## If ``limit`` more then 0, then read is limited to ``limit`` bytes.
checkClosed(transp) checkClosed(transp)
checkPending(transp) checkPending(transp)