From 453a5207eda52939181233bffffa67171ef838bd Mon Sep 17 00:00:00 2001 From: Caleb Maclennan Date: Sat, 11 Nov 2023 08:07:36 +0300 Subject: style(docs): Trim trailing whitespace in HTML docs Many editors remove these automatically anyway which makes opening and editng the docs cause a bunch of noise. This is just to get the noise out of the way in a style commit so it doesn't leak into other PRs --- docs/introduction.html | 110 ++++++++++++++++++++++++------------------------- 1 file changed, 55 insertions(+), 55 deletions(-) (limited to 'docs/introduction.html') diff --git a/docs/introduction.html b/docs/introduction.html index fd22f48..51443a0 100644 --- a/docs/introduction.html +++ b/docs/introduction.html @@ -1,11 +1,11 @@ - +Library, Support"> LuaSocket: Introduction to the core @@ -29,7 +29,7 @@ Library, Support"> download · installation · introduction · -reference +reference

@@ -61,23 +61,23 @@ interface to I/O across different domains and operating systems. The API design had two goals in mind. First, users experienced with the C API to sockets should feel comfortable using LuaSocket. Second, the simplicity and the feel of the Lua language should be -preserved. To achieve these goals, the LuaSocket API keeps the function names and semantics the C API whenever possible, but their usage in Lua has been greatly simplified. +preserved. To achieve these goals, the LuaSocket API keeps the function names and semantics the C API whenever possible, but their usage in Lua has been greatly simplified.

One of the simplifications is the receive pattern capability. -Applications can read data from stream domains (such as TCP) +Applications can read data from stream domains (such as TCP) line by line, block by block, or until the connection is closed. All I/O reads are buffered and the performance differences between -different receive patterns are negligible. +different receive patterns are negligible.

Another advantage is the flexible timeout control mechanism. As in C, all I/O operations are blocking by default. For -example, the send, -receive and +example, the send, +receive and accept methods of the TCP domain will block the caller application until the operation is completed (if ever!). However, with a call to the @@ -87,7 +87,7 @@ the time it can be blocked by LuaSocket (the "total" timeout), on the time LuaSocket can internally be blocked by any OS call (the "block" timeout) or a combination of the two. Each LuaSocket call might perform several OS calls, so that the two timeout values are -not equivalent. +not equivalent.

@@ -95,10 +95,10 @@ Finally, the host name resolution is transparent, meaning that most functions and methods accept both IP addresses and host names. In case a host name is given, the library queries the system's resolver and tries the main IP address returned. Note that direct use of IP addresses -is more efficient, of course. The -toip -and tohostname -functions from the DNS module are provided to convert between host names and IP addresses. +is more efficient, of course. The +toip +and tohostname +functions from the DNS module are provided to convert between host names and IP addresses.

@@ -118,47 +118,47 @@ reassembled transparently on the other end. There are no boundaries in the data transfers. The library allows users to read data from the sockets in several different granularities: patterns are available for lines, arbitrary sized blocks or "read up to connection closed", all with -good performance. +good performance.

-The library distinguishes three types of TCP sockets: master, -client and server sockets. +The library distinguishes three types of TCP sockets: master, +client and server sockets.

Master sockets are newly created TCP sockets returned by the function -socket.tcp. A master socket is +socket.tcp. A master socket is transformed into a server socket after it is associated with a local address by a call to the -bind method followed by a call to the -listen. Conversely, a master socket -can be changed into a client socket with the method -connect, -which associates it with a remote address. +bind method followed by a call to the +listen. Conversely, a master socket +can be changed into a client socket with the method +connect, +which associates it with a remote address.

-On server sockets, applications can use the +On server sockets, applications can use the accept method to wait for a client connection. Once a connection is established, a client socket object is returned representing this connection. The other methods available for server socket objects are -getsockname, +getsockname, setoption, -settimeout, and -close. +settimeout, and +close.

Client sockets are used to exchange data between two applications over -the Internet. Applications can call the methods +the Internet. Applications can call the methods send and -receive +receive to send and receive data. The other methods -available for client socket objects are +available for client socket objects are getsockname, -getpeername, +getpeername, setoption, settimeout, shutdown, and @@ -175,7 +175,7 @@ port (one that is chosen by the operating system) on the local host and awaits client connections on that port. When a connection is established, the program reads a line from the remote end and sends it back, closing the connection immediately. You can test it using the telnet -program. +program. 

@@ -217,68 +217,68 @@ error free. Data  transfers are atomic, one datagram at  a time. Reading
 only  part of  a  datagram discards  the  rest, so  that  the following read
 operation  will  act  on  the  next  datagram.  The  advantages  are  in
 simplicity (no connection  setup) and performance (no  error checking or
-error correction). 
+error correction).
 

 
 

 Note that although no guarantees are made, these days
-networks are so good that, under normal circumstances, few errors 
+networks are so good that, under normal circumstances, few errors
 happen in practice.
 

 
 

-An UDP socket object is  created by the 
+An UDP socket object is  created by the
 socket.udp function. UDP
 sockets  do   not  need   to  be  connected   before  use.   The  method
-sendto  
+sendto
 can  be  used  immediately after  creation  to
 send  a datagram to  IP address and port. Host names  are not allowed
 because performing name resolution for each packet would be forbiddingly
-slow.  Methods 
-receive  and 
+slow.  Methods
+receive  and
 receivefrom
 can be used to retrieve datagrams, the latter returning the IP and port of
 the  sender  as  extra  return  values (thus being  slightly  less
-efficient). 
+efficient).
 

 
 

 When  communication  is performed  repeatedly  with  a single  peer,  an
-application  should call  the 
+application  should call  the
 setpeername method to specify a
-permanent partner.  Methods 
+permanent partner.  Methods
 sendto and
-receivefrom 
+receivefrom
 can no longer be used, but the method
-send can be used to send data 
-directly  to   the   peer, and the method 
-receive 
+send can be used to send data
+directly  to   the   peer, and the method
+receive
 will  only return  datagrams originating
 from that peer. There is about 30% performance gain due to this practice.
 

 
 

-To associate  an UDP socket with  a local address, an  application calls the   
-setsockname 
+To associate  an UDP socket with  a local address, an  application calls the
+setsockname
 method before sending any datagrams.   Otherwise, the socket is
 automatically  bound  to an  ephemeral  address  before the  first  data
-transmission and once bound the local address cannot be changed.  
+transmission and once bound the local address cannot be changed.
 The   other  methods   available  for  UDP   sockets  are
-getpeername,  
-getsockname, 
+getpeername,
+getsockname,
 settimeout,
-setoption and 
-close. 
+setoption and
+close.
 

 
 

-Example: 
+Example:
 

 

 

 A simple daytime client, using LuaSocket. The program connects to a remote
 server and tries to retrieve the daytime, printing the answer it got or an
-error message. 
+error message.
 

 
 
@@ -301,11 +301,11 @@ io.write(assert(udp:receive()))
 
 
Support modules

 
-
 Although not covered in the introduction, LuaSocket offers 
+
 Although not covered in the introduction, LuaSocket offers
 much more than TCP and UDP functionality. As the library
 evolved, support for HTTP, FTP,
 and SMTP were built on top of these. These modules
-and many others are covered by the reference manual. 
+and many others are covered by the reference manual.
 

 
 
-- 
cgit v1.2.3-55-g6feb