Moduł asyncore — Asynchroniczna obsługa gniazda

Source code: Lib/asyncore.py

Niezalecane od wersji 3.6: asyncore will be removed in Python 3.12 (see PEP 594 for details). Please use asyncio instead.

---

Informacja

This module exists for backwards compatibility only. For new code we recommend using asyncio.

Ten moduł dostarcza podstawową infrastrukturę do pisania asynchronicznych klientów i serwerów usługi gniazd.

Istnieją tylko dwa sposoby aby program na pojedynczym procesorze robił „więcej niż jedną rzecz na raz.” Wielo-wątkowe programowanie jest najprostszą i najczęściej spotykaną drogą aby to robić, ale istnieje inna bardzo odmienna technika, która pozwala mieć prawie wszystkie zalety wielowątkowości, bez używania wielu wątków. Jest ona tylko pomocna jeśli twój program jest w większości związany z wejściem/wyjściem. Jeśli twój program jest związany z procesorem, wtedy wywłaszczające planowane wątki są najczęściej tym czego potrzebujesz. Serwery sieciowe jednakże są rzadko związane z procesorem.

If your operating system supports the select() system call in its I/O library (and nearly all do), then you can use it to juggle multiple communication channels at once; doing other work while your I/O is taking place in the „background.” Although this strategy can seem strange and complex, especially at first, it is in many ways easier to understand and control than multi-threaded programming. The asyncore module solves many of the difficult problems for you, making the task of building sophisticated high-performance network servers and clients a snap. For „conversational” applications and protocols the companion asynchat module is invaluable.

Podstawowym pomysłem stojącym za oboma modułami jest stworzenie jednego lub więcej kanałów, przykładów uogólnienia asyncore.dispatcher i asynchat.async_chat. Utworzenie kanałów dodaje je do globalnej mapy, używanej przez funkcję loop() jeśli dostarczysz jej swojej własnej mapy.

Gdy początkowy(e) kanał(y) jest(są) tworzony(e), wywołanie funkcji loop() aktywuje usługę kanału, która kontynuuje zanim ostatni kanał (włączając w to jakiekolwiek które zostały dodane do mapy podczas asynchronicznej usługi) nie zostanie zamknięty.

asyncore.loop([timeout[, use_poll[, map[, count]]]])

Enter a polling loop that terminates after count passes or all open channels have been closed. All arguments are optional. The count parameter defaults to None, resulting in the loop terminating only when all channels have been closed. The timeout argument sets the timeout parameter for the appropriate select() or poll() call, measured in seconds; the default is 30 seconds. The use_poll parameter, if true, indicates that poll() should be used in preference to select() (the default is False).

Parametr map jest słownikiem którego elementami są kanały do oglądania. Gdy kanały są zamykane są one kasowane z ich mapy. Jeśli mapa jest pominięta, nadrzędna mapa jest używana. Kanały (przykłady uogólnienia asyncore.dispatcher i asynchat.async_chat i podrzędne uogólnienia tychże) mogą dowolnie być mieszane wewnątrz mapy.

class asyncore.dispatcher

Uogólnienie dispatcher jest cienkim opakowaniem wokół niskopoziomowego przedmiotu gniazda. Aby uczynić je bardziej użytecznym, ma kilka sposobów postępowania dla obsługi-zdarzeń które są wzywane z asynchronicznej pętli. Poza tym, może być traktowana jako zwyczajny nieblokujący przedmiot gniazda.

Odpalanie niskopoziomowych zdarzeń w konkretnych momentach lub w konkretnych stanach połączeń mówi pętli asynchronicznej że konkretne wyższego poziomu zdarzenia miały miejsce. Dla przykładu, jeśli żądaliśmy aby gniazdo podłączone było do innego hosta, wiemy że połączenie zostało ustanowione gdy gniazdo stanie się możliwe do zapisania po raz pierwszy (w tym momencie wiesz że możesz zapisać do niego oczekując powodzenia). Dorozumiane zdarzenia wyższego poziomu to:

Zdarzenie	Opis
handle_connect()	Domyślne przez pierwsze zdarzenie odczytu lub zapisu
handle_close()	Domyślne przy zdarzeniu odczytu bez dostępnych danych
handle_accepted()	Domyślne przy zdarzeniu czytania na nasłuchującym gnieździe

During asynchronous processing, each mapped channel’s readable() and writable() methods are used to determine whether the channel’s socket should be added to the list of channels select()ed or poll()ed for read and write events.

Dlatego, zestaw zdarzeń kanałów jest większy, niż podstawowych zdarzeń gniazda. Pełny zestaw sposobów postępowania, które mogą być przesłonięte w twoim podrzędnym uogólnieniu jest następujący:

handle_read()

Wywoływane, gdy asynchroniczna pętla wykryje, że wywołanie read() na gnieździe kanału odniesie sukces.

handle_write()

Wywoływane, gdy asynchroniczna pętla wykryje, że możliwe do zapisu gniazdo może być zapisane. Często ten sposób postępowania będzie wypełniał konieczne wczytywanie z wyprzedzeniem dla poprawy wydajności. Dla przykładu:

def handle_write(self):
    sent = self.send(self.buffer)
    self.buffer = self.buffer[sent:]

handle_expt()

Wywoływane gdy są dane poza zakresem (OOB) dla połączenia z gniazdem. To raczej nie wystąpi nigdy, jako że OOB jest rzadko wspierany i rzadziej jeszcze używany.

handle_connect()

Wywoływane gdy gniazdo aktywnego otwierającego właściwie wywoła połączenie. Może wysłać „powitalny” banner, lub zainicjować negocjację protokołu z zewnętrznym punktem końcowym, dla przykładu.

handle_close()

Wywoływany gdy gniazdo jest zamykane.

handle_error()

Wywoływane gdy wyjątek jest zgłaszany i nie jest inaczej obsługiwany. Domyślna wersja wypisuje skumulowany wypis.

handle_accept()

Called on listening channels (passive openers) when a connection can be established with a new remote endpoint that has issued a connect() call for the local endpoint. Deprecated in version 3.2; use handle_accepted() instead.

Niezalecane od wersji 3.2.

handle_accepted(sock, addr)

Called on listening channels (passive openers) when a connection has been established with a new remote endpoint that has issued a connect() call for the local endpoint. sock is a new socket object usable to send and receive data on the connection, and addr is the address bound to the socket on the other end of the connection.

Nowe w wersji 3.2.

readable()

Wywoływane za każdym razem dla asynchronicznej pętli aby ustalić, czy gniazdo kanału powinno być dodane do listy na której zdarzenia wczytywania mogą następować. Domyślny sposób po prostu zwraca Prawdę - z ang. - True, wskazując że domyślnie wszystkie kanały będą zainteresowane zdarzeniami wczytywania.

writable()

Wywoływane za każdym razem dla asynchronicznej pętli aby ustalić, czy gniazdo kanału powinno być dodawane do listy na której zdarzenia zapisu mogą następować. Domyślny sposób postępowania po prostu zwraca Prawdę - z ang. - True, wskazując że domyślnie, wszystkie kanały będą zainteresowane zdarzeniami zapisu.

Na dodatek, każdy kanał deleguje lub rozszerza wiele ze sposobów postępowania gniazd. Większość z tych jest prawie identyczna z ich partnerami gniazda.

create_socket(family=socket.AF_INET, type=socket.SOCK_STREAM)

To jest identyczne z utworzeniem normalnego gniazda, i będzie używało tych samych opcji dla tworzenia. Zajrzyj do dokumentacji do socket po więcej informacji o tworzeniu gniazd.

Zmienione w wersji 3.3: family and type arguments can be omitted.

connect(address)

Tak jak z normalnymi przedmiotami gniazd, adres - z ang. - address jest krotką z pierwszym elementem hosta do którego się podłącza, i drugim numerem portu.

send(data)

Prześlij dane - z ang. - data do odległego punktu końcowego gniazda.

recv(buffer_size)

Read at most buffer_size bytes from the socket’s remote end-point. An empty bytes object implies that the channel has been closed from the other end.

Note that recv() may raise BlockingIOError , even though select.select() or select.poll() has reported the socket ready for reading.

listen(backlog)

Nasłuchuj połączeń wykonywanych do gniazda. Parametr wstecznego logu - z ang. - backlog określa maksymalną liczbę kolejkowanych połączeń i powinien być równy przynajmniej 1; Wartość maksymalna jest zależna od systemu (zwykle jest równa 5).

bind(address)

Połącz gniazdo z adresem. Gniazdo nie może być już połączone z adresem. (Format adresu zależy od rodziny adresów — zajrzyj do dokumentacji socket po więcej informacji.) Aby oznaczyć gniazdo jako możliwe do ponownego użycia - z ang. - re-usable (ustawiając opcję SO_REUSEADDR), wywołaj sposób postępowania set_reuse_addr() obiektu dispatcher.

accept()

Accept a connection. The socket must be bound to an address and listening for connections. The return value can be either None or a pair (conn, address) where conn is a new socket object usable to send and receive data on the connection, and address is the address bound to the socket on the other end of the connection. When None is returned it means the connection didn’t take place, in which case the server should just ignore this event and keep listening for further incoming connections.

close()

Zamknij gniazdo. Wszystkie przyszłe operacje na gnieździe zawiodą. Odległy koniec nie dostanie więcej danych (po tym jak zakolejkowane dane zostaną przesłane). Gniazda są automatycznie zamykane gdy są poddawane zbieraniu śmieci.

class asyncore.dispatcher_with_send

A dispatcher subclass which adds simple buffered output capability, useful for simple clients. For more sophisticated usage use asynchat.async_chat.

class asyncore.file_dispatcher

A file_dispatcher takes a file descriptor or file object along with an optional map argument and wraps it for use with the poll() or loop() functions. If provided a file object or anything with a fileno() method, that method will be called and passed to the file_wrapper constructor.

Availability: Unix.

class asyncore.file_wrapper

A file_wrapper takes an integer file descriptor and calls os.dup() to duplicate the handle so that the original handle may be closed independently of the file_wrapper. This class implements sufficient methods to emulate a socket for use by the file_dispatcher class.

Availability: Unix.

Podstawowy klient HTTP Przykładu asyncore

Tu jest bardzo podstawowy klient HTTP który używa uogólnienia dispatcher do wypełnienia jego obsługi gniazda:

import asyncore

class HTTPClient(asyncore.dispatcher):

    def __init__(self, host, path):
        asyncore.dispatcher.__init__(self)
        self.create_socket()
        self.connect( (host, 80) )
        self.buffer = bytes('GET %s HTTP/1.0\r\nHost: %s\r\n\r\n' %
                            (path, host), 'ascii')

    def handle_connect(self):
        pass

    def handle_close(self):
        self.close()

    def handle_read(self):
        print(self.recv(8192))

    def writable(self):
        return (len(self.buffer) > 0)

    def handle_write(self):
        sent = self.send(self.buffer)
        self.buffer = self.buffer[sent:]


client = HTTPClient('www.python.org', '/')
asyncore.loop()

asyncore Example basic echo server

Here is a basic echo server that uses the dispatcher class to accept connections and dispatches the incoming connections to a handler:

import asyncore

class EchoHandler(asyncore.dispatcher_with_send):

    def handle_read(self):
        data = self.recv(8192)
        if data:
            self.send(data)

class EchoServer(asyncore.dispatcher):

    def __init__(self, host, port):
        asyncore.dispatcher.__init__(self)
        self.create_socket()
        self.set_reuse_addr()
        self.bind((host, port))
        self.listen(5)

    def handle_accepted(self, sock, addr):
        print('Incoming connection from %s' % repr(addr))
        handler = EchoHandler(sock)

server = EchoServer('localhost', 8080)
asyncore.loop()