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()
