LuaSocket: Introduction to the core

From f98977b2dac48fc66822402b095336e683715126 Mon Sep 17 00:00:00 2001 From: Caleb Maclennan Date: Wed, 23 Mar 2022 00:09:53 +0300 Subject: Move doc→docs so we can serve it with GitHub Pages MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- doc/introduction.html | 333 -------------------------------------------------- 1 file changed, 333 deletions(-) delete mode 100644 doc/introduction.html (limited to 'doc/introduction.html') diff --git a/doc/introduction.html b/doc/introduction.html deleted file mode 100644 index fd22f48..0000000 --- a/doc/introduction.html +++ /dev/null @@ -1,333 +0,0 @@ - - - - - - -LuaSocket: Introduction to the core - - - - - - - - - - - -

Introduction

- -

-LuaSocket is a Lua extension library -that is composed by two parts: a C core that provides support for the TCP -and UDP transport layers, and a set of Lua modules that add support for -the SMTP (sending e-mails), HTTP (WWW access) and FTP (uploading and -downloading files) protocols and other functionality commonly needed by -applications that deal with the Internet. This introduction is about the C -core. -

- -

-Communication in LuaSocket is performed via I/O objects. These can -represent different network domains. Currently, support is provided for TCP -and UDP, but nothing prevents other developers from implementing SSL, Local -Domain, Pipes, File Descriptors etc. I/O objects provide a standard -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. -

- - -

-One of the simplifications is the receive pattern capability. -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. -

- -

-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 -accept methods -of the TCP domain will block the caller application until -the operation is completed (if ever!). However, with a call to the -settimeout -method, an application can specify upper limits on -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. -

- -

-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. -

- -

-Together, these changes make network programming in LuaSocket much simpler -than it is in C, as the following sections will show. -

- - - -

TCP

- -

-TCP (Transfer Control Protocol) is reliable stream protocol. In other -words, applications communicating through TCP can send and receive data as -an error free stream of bytes. Data is split in one end and -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. -

- -

-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 -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. -

- -

-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, -setoption, -settimeout, and -close. -

- -

-Client sockets are used to exchange data between two applications over -the Internet. Applications can call the methods -send and -receive -to send and receive data. The other methods -available for client socket objects are -getsockname, -getpeername, -setoption, -settimeout, -shutdown, and -close. -

- -

-Example: -

-
-A simple echo server, using LuaSocket. The program binds to an ephemeral -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. -
- -
--- load namespace
-local socket = require("socket")
--- create a TCP socket and bind it to the local host, at any port
-local server = assert(socket.bind("*", 0))
--- find out which port the OS chose for us
-local ip, port = server:getsockname()
--- print a message informing what's up
-print("Please telnet to localhost on port " .. port)
-print("After connecting, you have 10s to enter a line to be echoed")
--- loop forever waiting for clients
-while 1 do
-  -- wait for a connection from any client
-  local client = server:accept()
-  -- make sure we don't block waiting for this client's line
-  client:settimeout(10)
-  -- receive the line
-  local line, err = client:receive()
-  -- if there was no error, send it back to the client
-  if not err then client:send(line .. "\n") end
-  -- done with client, close the object
-  client:close()
-end
-
-

- - - -

UDP

- -

-UDP (User Datagram Protocol) is a non-reliable datagram protocol. In -other words, applications communicating through UDP send and receive -data as independent blocks, which are not guaranteed to reach the other -end. Even when they do reach the other end, they are not guaranteed to be -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). -

- -

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

- -

-An UDP socket object is created by the -socket.udp function. UDP -sockets do not need to be connected before use. The method -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 -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). -

- -

-When communication is performed repeatedly with a single peer, an -application should call the -setpeername method to specify a -permanent partner. Methods -sendto and -receivefrom -can no longer be used, but the method -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 -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. -The other methods available for UDP sockets are -getpeername, -getsockname, -settimeout, -setoption and -close. -

- -

-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. -

- -

--- change here to the host an port you want to contact
-local host, port = "localhost", 13
--- load namespace
-local socket = require("socket")
--- convert host name to ip address
-local ip = assert(socket.dns.toip(host))
--- create a new UDP object
-local udp = assert(socket.udp())
--- contact daytime host
-assert(udp:sendto("anything", ip, port))
--- retrieve the answer and print results
-io.write(assert(udp:receive()))
-

- - - -

Support modules

- -

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. -

- - - - - - - -- cgit v1.2.3-55-g6feb