### Navigation
- [index](# "General Index")
- [modules](# "Python Module Index") |
- [next](# "Coroutines and concurrency") |
- [previous](# "tornado.tcpclient — IOStream connection factory") |
- [Tornado 4.4.dev1 documentation](#) »
- [Asynchronous networking](#) »
# `tornado.tcpserver` — Basic [`IOStream`](# "tornado.iostream.IOStream")-based TCP server
A non-blocking, single-threaded TCP server.
*class *`tornado.tcpserver.``TCPServer`(*io_loop=None*, *ssl_options=None*, *max_buffer_size=None*, *read_chunk_size=None*)[[source]](#)
A non-blocking, single-threaded TCP server.
To use [`TCPServer`](# "tornado.tcpserver.TCPServer"), define a subclass which overrides the [`handle_stream`](# "tornado.tcpserver.TCPServer.handle_stream")method.
To make this server serve SSL traffic, send the `ssl_options` keywordargument with an [`ssl.SSLContext`](https://docs.python.org/3.4/library/ssl.html#ssl.SSLContext "(in Python v3.4)") [https://docs.python.org/3.4/library/ssl.html#ssl.SSLContext] object. For compatibility with olderversions of Python `ssl_options` may also be a dictionary of keywordarguments for the [`ssl.wrap_socket`](https://docs.python.org/3.4/library/ssl.html#ssl.wrap_socket "(in Python v3.4)") [https://docs.python.org/3.4/library/ssl.html#ssl.wrap_socket] method.:
~~~
ssl_ctx = ssl.create_default_context(ssl.Purpose.CLIENT_AUTH)
ssl_ctx.load_cert_chain(os.path.join(data_dir, "mydomain.crt"),
os.path.join(data_dir, "mydomain.key"))
TCPServer(ssl_options=ssl_ctx)
~~~
[`TCPServer`](# "tornado.tcpserver.TCPServer") initialization follows one of three patterns:
1.
[`listen`](# "tornado.tcpserver.TCPServer.listen"): simple single-process:
~~~
server = TCPServer()
server.listen(8888)
IOLoop.current().start()
~~~
1.
[`bind`](# "tornado.tcpserver.TCPServer.bind")/[`start`](# "tornado.tcpserver.TCPServer.start"): simple multi-process:
~~~
server = TCPServer()
server.bind(8888)
server.start(0) # Forks multiple sub-processes
IOLoop.current().start()
~~~
When using this interface, an [`IOLoop`](# "tornado.ioloop.IOLoop") must *not* be passedto the [`TCPServer`](# "tornado.tcpserver.TCPServer") constructor. [`start`](# "tornado.tcpserver.TCPServer.start") will always startthe server on the default singleton [`IOLoop`](# "tornado.ioloop.IOLoop").
1.
[`add_sockets`](# "tornado.tcpserver.TCPServer.add_sockets"): advanced multi-process:
~~~
sockets = bind_sockets(8888)
tornado.process.fork_processes(0)
server = TCPServer()
server.add_sockets(sockets)
IOLoop.current().start()
~~~
The [`add_sockets`](# "tornado.tcpserver.TCPServer.add_sockets") interface is more complicated, but it can beused with [`tornado.process.fork_processes`](# "tornado.process.fork_processes") to give you moreflexibility in when the fork happens. [`add_sockets`](# "tornado.tcpserver.TCPServer.add_sockets") canalso be used in single-process servers if you want to createyour listening sockets in some way other than[`bind_sockets`](# "tornado.netutil.bind_sockets").
New in version 3.1: The `max_buffer_size` argument.
`listen`(*port*, *address=''*)[[source]](#)
Starts accepting connections on the given port.
This method may be called more than once to listen on multiple ports.[`listen`](# "tornado.tcpserver.TCPServer.listen") takes effect immediately; it is not necessary to call[`TCPServer.start`](# "tornado.tcpserver.TCPServer.start") afterwards. It is, however, necessary to startthe [`IOLoop`](# "tornado.ioloop.IOLoop").
`add_sockets`(*sockets*)[[source]](#)
Makes this server start accepting connections on the given sockets.
The `sockets` parameter is a list of socket objects such asthose returned by [`bind_sockets`](# "tornado.netutil.bind_sockets").[`add_sockets`](# "tornado.tcpserver.TCPServer.add_sockets") is typically used in combination with thatmethod and [`tornado.process.fork_processes`](# "tornado.process.fork_processes") to provide greatercontrol over the initialization of a multi-process server.
`add_socket`(*socket*)[[source]](#)
Singular version of [`add_sockets`](# "tornado.tcpserver.TCPServer.add_sockets"). Takes a single socket object.
`bind`(*port*, *address=None*, *family=<AddressFamily.AF_UNSPEC: 0>*, *backlog=128*, *reuse_port=False*)[[source]](#)
Binds this server to the given port on the given address.
To start the server, call [`start`](# "tornado.tcpserver.TCPServer.start"). If you want to run this serverin a single process, you can call [`listen`](# "tornado.tcpserver.TCPServer.listen") as a shortcut to thesequence of [`bind`](# "tornado.tcpserver.TCPServer.bind") and [`start`](# "tornado.tcpserver.TCPServer.start") calls.
Address may be either an IP address or hostname. If it's a hostname,the server will listen on all IP addresses associated with thename. Address may be an empty string or None to listen on allavailable interfaces. Family may be set to either [`socket.AF_INET`](https://docs.python.org/3.4/library/socket.html#socket.AF_INET "(in Python v3.4)") [https://docs.python.org/3.4/library/socket.html#socket.AF_INET]or [`socket.AF_INET6`](https://docs.python.org/3.4/library/socket.html#socket.AF_INET6 "(in Python v3.4)") [https://docs.python.org/3.4/library/socket.html#socket.AF_INET6] to restrict to IPv4 or IPv6 addresses, otherwiseboth will be used if available.
The `backlog` argument has the same meaning as for[`socket.listen`](https://docs.python.org/3.4/library/socket.html#socket.socket.listen "(in Python v3.4)") [https://docs.python.org/3.4/library/socket.html#socket.socket.listen].
This method may be called multiple times prior to [`start`](# "tornado.tcpserver.TCPServer.start") to listenon multiple ports or interfaces.
`start`(*num_processes=1*)[[source]](#)
Starts this server in the [`IOLoop`](# "tornado.ioloop.IOLoop").
By default, we run the server in this process and do not fork anyadditional child process.
If num_processes is `None` or <= 0, we detect the number of coresavailable on this machine and fork that number of childprocesses. If num_processes is given and > 1, we fork thatspecific number of sub-processes.
Since we use processes and not threads, there is no shared memorybetween any server code.
Note that multiple processes are not compatible with the autoreloadmodule (or the `autoreload=True` option to [`tornado.web.Application`](# "tornado.web.Application")which defaults to True when `debug=True`).When using multiple processes, no IOLoops can be created orreferenced until after the call to `TCPServer.start(n)`.
`stop`()[[source]](#)
Stops listening for new connections.
Requests currently in progress may still continue after theserver is stopped.
`handle_stream`(*stream*, *address*)[[source]](#)
Override to handle a new [`IOStream`](# "tornado.iostream.IOStream") from an incoming connection.
This method may be a coroutine; if so any exceptions it raisesasynchronously will be logged. Accepting of incoming connectionswill not be blocked by this coroutine.
If this [`TCPServer`](# "tornado.tcpserver.TCPServer") is configured for SSL, `handle_stream`may be called before the SSL handshake has completed. Use[`SSLIOStream.wait_for_handshake`](# "tornado.iostream.SSLIOStream.wait_for_handshake") if you need to verify the client'scertificate or use NPN/ALPN.
Changed in version 4.2: Added the option for this method to be a coroutine.
© Copyright 2009-2016, The Tornado Authors. Created using [Sphinx](http://sphinx-doc.org/) 1.3.5.
- User's guide
- Introduction
- Asynchronous and non-Blocking I/O
- Coroutines
- Queue example - a concurrent web spider
- Structure of a Tornado web application
- Templates and UI
- Authentication and security
- Running and deploying
- Web framework
- tornado.web — RequestHandler and Application classes
- tornado.template — Flexible output generation
- tornado.escape — Escaping and string manipulation
- tornado.locale — Internationalization support
- tornado.websocket — Bidirectional communication to the browser
- HTTP servers and clients
- tornado.httpserver — Non-blocking HTTP server
- tornado.httpclient — Asynchronous HTTP client
- tornado.httputil — Manipulate HTTP headers and URLs
- tornado.http1connection – HTTP/1.x client/server implementation
- Asynchronous networking
- tornado.ioloop — Main event loop
- tornado.iostream — Convenient wrappers for non-blocking sockets
- tornado.netutil — Miscellaneous network utilities
- tornado.tcpclient — IOStream connection factory
- tornado.tcpserver — Basic IOStream-based TCP server
- Coroutines and concurrency
- tornado.gen — Simplify asynchronous code
- tornado.concurrent — Work with threads and futures
- tornado.locks – Synchronization primitives
- tornado.queues – Queues for coroutines
- tornado.process — Utilities for multiple processes
- Integration with other services
- tornado.auth — Third-party login with OpenID and OAuth
- tornado.wsgi — Interoperability with other Python frameworks and servers
- tornado.platform.asyncio — Bridge between asyncio and Tornado
- tornado.platform.caresresolver — Asynchronous DNS Resolver using C-Ares
- tornado.platform.twisted — Bridges between Twisted and Tornado
- Utilities
- tornado.autoreload — Automatically detect code changes in development
- tornado.log — Logging support
- tornado.options — Command-line parsing
- tornado.stack_context — Exception handling across asynchronous callbacks
- tornado.testing — Unit testing support for asynchronous code
- tornado.util — General-purpose utilities
- Frequently Asked Questions
- Release notes
- What's new in Tornado 4.3
- What's new in Tornado 4.2.1
- What's new in Tornado 4.2
- What's new in Tornado 4.1
- What's new in Tornado 4.0.2
- What's new in Tornado 4.0.1
- What's new in Tornado 4.0
- What's new in Tornado 3.2.2
- What's new in Tornado 3.2.1
- What's new in Tornado 3.2
- What's new in Tornado 3.1.1
- What's new in Tornado 3.1
- What's new in Tornado 3.0.2
- What's new in Tornado 3.0.1
- What's new in Tornado 3.0
- What's new in Tornado 2.4.1
- What's new in Tornado 2.4
- What's new in Tornado 2.3
- What's new in Tornado 2.2.1
- What's new in Tornado 2.2
- What's new in Tornado 2.1.1
- What's new in Tornado 2.1
- What's new in Tornado 2.0
- What's new in Tornado 1.2.1
- What's new in Tornado 1.2
- What's new in Tornado 1.1.1
- What's new in Tornado 1.1
- What's new in Tornado 1.0.1
- What's new in Tornado 1.0