selectors — I/O-multiplexering på hög nivå

Tillagd i version 3.4.

Källkod: Lib/selectors.py

Introduktion

Den här modulen möjliggör effektiv I/O-multiplexering på hög nivå och bygger på select-modulens primitiver. Användare uppmanas att använda den här modulen istället, såvida de inte vill ha exakt kontroll över de primitiver på OS-nivå som används.

Den definierar en BaseSelector abstrakt basklass, tillsammans med flera konkreta implementationer (KqueueSelector, EpollSelector…), som kan användas för att vänta på I/O-beredskapsmeddelande på flera filobjekt. I det följande avser ”filobjekt” alla objekt med en fileno()-metod eller en rå filbeskrivare. Se filobjekt.

DefaultSelector är ett alias för den mest effektiva implementationen som finns tillgänglig på den aktuella plattformen: detta bör vara standardvalet för de flesta användare.

Anteckning

Vilken typ av filobjekt som stöds beror på plattformen: på Windows stöds sockets, men inte pipes, medan båda stöds på Unix (vissa andra typer kan också stödjas, t.ex. fifos eller speciella filenheter).

Se även

välja

Modul för I/O-multiplexering på låg nivå.

Tillgänglighet: not WASI.

Den här modulen fungerar inte eller är inte tillgänglig på WebAssembly. Se WebAssembly-plattformar för mer information.

Klasser

Klasser-hierarki:

BaseSelector
+-- SelectSelector
+-- PollSelector
+-- EpollSelector
+-- DevpollSelector
+-- KqueueSelector

I det följande är events en bitvis mask som anger vilka I/O-händelser som ska inväntas för ett visst filobjekt. Den kan vara en kombination av modulkonstanterna nedan:

Konstant

Betydelse
selectors.EVENT_READ

Tillgänglig för läsning
selectors.EVENT_WRITE

Tillgänglig för skrivning
class selectors.SelectorKey

En SelectorKey är en namedtuple som används för att associera ett filobjekt till dess underliggande filbeskrivning, valda händelsemask och bifogade data. Den returneras av flera BaseSelector-metoder.

fileobj

Filobjekt registrerat.

fd

Underliggande filbeskrivare.

events

Händelser som måste inväntas för detta filobjekt.

data

Valfri opak data som är kopplad till filobjektet: kan t.ex. användas för att lagra ett sessions-ID för varje klient.

class selectors.BaseSelector

En BaseSelector används för att vänta på I/O-händelser på flera filobjekt. Den stöder registrering och avregistrering av filströmmar och en metod för att vänta på I/O-händelser i dessa strömmar, med en valfri timeout. Det är en abstrakt basklass, så den kan inte instansieras. Använd DefaultSelector istället, eller en av SelectSelector, KqueueSelector etc. om du specifikt vill använda en implementation, och din plattform stödjer det. BaseSelector och dess konkreta implementationer stödjer context manager protokollet.

abstractmethod register(fileobj, events, data=None)

Registrera ett filobjekt för val och övervaka det för I/O-händelser.

fileobj är det filobjekt som ska övervakas. Det kan antingen vara en filbeskrivare med heltal eller ett objekt med en fileno()-metod. events är en bitvis mask av händelser som ska övervakas. data är ett opakt objekt.

Detta returnerar en ny SelectorKey-instans, eller ger upphov till ett ValueError om händelsemasken eller filbeskrivningen är ogiltig, eller KeyError om filobjektet redan är registrerat.

abstractmethod unregister(fileobj)

Avregistrera ett filobjekt från urvalet och ta bort det från övervakning. Ett filobjekt ska avregistreras innan det stängs.

fileobj måste vara ett filobjekt som tidigare registrerats.

Detta returnerar den associerade SelectorKey-instansen, eller ger upphov till KeyError om fileobj inte är registrerad. Den ger upphov till ValueError om fileobj är ogiltig (t.ex. om den inte har någon fileno()-metod eller om dess fileno()-metod har ett ogiltigt returvärde).

modify(fileobj, events, data=None)

Ändra ett registrerat filobjekts övervakade händelser eller bifogade data.

Detta är likvärdigt med BaseSelector.unregister(fileobj) följt av BaseSelector.register(fileobj, events, data), förutom att det kan implementeras mer effektivt.

Detta returnerar en ny SelectorKey-instans, eller ger upphov till ett ValueError i händelse av ogiltig händelsemask eller filbeskrivning, eller KeyError om filobjektet inte är registrerat.

abstractmethod select(timeout=None)

Vänta tills några registrerade filobjekt blir klara eller tills timeouten löper ut.

Om timeout > 0, anger detta den maximala väntetiden i sekunder. Om timeout <= 0 kommer anropet inte att blockeras och rapporterar de filobjekt som för närvarande är klara. Om timeout är None kommer anropet att blockeras tills ett övervakat filobjekt blir klart.

Detta returnerar en lista med (key, events)-tupler, en för varje färdigt filobjekt.

key är den instans av SelectorKey som motsvarar ett färdigt filobjekt. events är en bitmask av händelser som är klara för detta filobjekt.

Anteckning

Denna metod kan returneras innan något filobjekt blir klart eller timeouten har löpt ut om den aktuella processen får en signal: i detta fall returneras en tom lista.

Ändrad i version 3.5: Väljaren försöker nu igen med en omräknad timeout när den avbryts av en signal om signalhanteraren inte utlöste ett undantag (se PEP 475 för förklaringen), istället för att returnera en tom lista med händelser före timeouten.

close()

Stäng väljaren.

Detta måste anropas för att säkerställa att alla underliggande resurser är frigjorda. Väljaren får inte användas när den har stängts.

get_key(fileobj)

Returnerar nyckeln som är kopplad till ett registrerat filobjekt.

Detta returnerar SelectorKey-instansen som är associerad med detta filobjekt, eller ger upphov till KeyError om filobjektet inte är registrerat.

abstractmethod get_map()

Returnerar en mappning av filobjekt till väljarknappar.

Detta returnerar en Mapping-instans som mappar registrerade filobjekt till deras associerade SelectorKey-instans.

class selectors.DefaultSelector

Standardväljarklassen använder den mest effektiva implementeringen som finns tillgänglig på den aktuella plattformen. Detta bör vara standardvalet för de flesta användare.

class selectors.SelectSelector

select.select()-baserad väljare.

class selectors.PollSelector

select.poll()-baserad väljare.

class selectors.EpollSelector

select.epoll()-baserad väljare.

fileno()

Detta returnerar filbeskrivaren som används av det underliggande select.epoll()-objektet.

class selectors.DevpollSelector

select.devpoll()-baserad väljare.

fileno()

Detta returnerar filbeskrivaren som används av det underliggande select.devpoll()-objektet.

Tillagd i version 3.5.

class selectors.KqueueSelector

select.kqueue()-baserad väljare.

fileno()

Detta returnerar filbeskrivaren som används av det underliggande select.kqueue()-objektet.

Exempel

Här är en enkel implementering av en ekoserver:

import selectors
import socket

sel = selectors.DefaultSelector()

def accept(sock, mask):
    conn, addr = sock.accept()  # Should be ready
    print('accepted', conn, 'from', addr)
    conn.setblocking(False)
    sel.register(conn, selectors.EVENT_READ, read)

def read(conn, mask):
    data = conn.recv(1000)  # Should be ready
    if data:
        print('echoing', repr(data), 'to', conn)
        conn.send(data)  # Hope it won't block
    else:
        print('closing', conn)
        sel.unregister(conn)
        conn.close()

sock = socket.socket()
sock.bind(('localhost', 1234))
sock.listen(100)
sock.setblocking(False)
sel.register(sock, selectors.EVENT_READ, accept)

while True:
    events = sel.select()
    for key, mask in events:
        callback = key.data
        callback(key.fileobj, mask)