select — wachten op gebeurtenissen op een set streams

Deze module biedt functies om efficiënt te wachten totdat een of meer streams (bestandachtige objecten die het stream-protocol implementeren, zoals sockets, UARTs en andere I/O-objecten) klaar zijn om te lezen of te schrijven, in plaats van actief te wachten (busy-waiting) of te blokkeren op een enkel object.

Het poll object is de aanbevolen interface: het schaalt naar veel streams en is allocatievrij wanneer het via poll.ipoll() wordt gebruikt. De select() functie op moduleniveau is een minder efficiënte compatibiliteitsinterface.

Voorbeeld met een poll object:

import select

poller = select.poll()
poller.register(uart, select.POLLIN)

while True:
    # Wait up to 1000 ms for the UART to have data.
    for obj, event in poller.poll(1000):
        if event & select.POLLIN:
            print(obj.read())

Voorbeeld met de select() functie op moduleniveau:

import select

# Wait up to 1 second for the socket to become readable.
rlist, wlist, xlist = select.select([sock], [], [], 1.0)
if rlist:
    data = sock.recv(100)

Functies

select.select(rlist: List, wlist: List, xlist: List, timeout: float | None = None) → Tuple[List, List, List]

Wacht totdat een of meer van de gegeven stream-objecten klaar zijn, of totdat timeout verloopt.

  • rlist is een lijst met objecten om te monitoren op leesbaarheid.

  • wlist is een lijst met objecten om te monitoren op schrijfbaarheid.

  • xlist is een lijst met objecten om te monitoren op een fout- of hang-up-conditie.

  • timeout is de maximale wachttijd, in seconden (een float wordt geaccepteerd). Als deze wordt weggelaten of None is, blokkeert de aanroep oneindig; 0 keert onmiddellijk terug (een niet-blokkerende poll).

Geeft een 3-tuple van lijsten (rlist, wlist, xlist) terug. Elke teruggegeven lijst is de subset van de overeenkomstige invoerlijst die de objecten bevat die respectievelijk gereed werden voor lezen, gereed werden voor schrijven, of een fout/hang-up signaleerden. Als timeout verloopt zonder dat er iets gereed is, zijn alle drie de lijsten leeg.

Deze functie is minder efficiënt dan poll (het bouwt zijn interne poll-set bij elke aanroep opnieuw op); gebruik waar mogelijk in plaats daarvan poll.

Constanten

select.POLLIN: int

Er zijn data beschikbaar om uit de stream te lezen.

select.POLLOUT: int

De stream kan meer data accepteren om te schrijven.

select.POLLERR: int

Er trad een foutconditie op de stream op. Dit is een ongevraagde gebeurtenis: deze wordt gerapporteerd door poll.poll() / poll.ipoll() zelfs als er niet om werd gevraagd in de eventmask, en het is niet geldig om deze als invoer-eventmask door te geven.

select.POLLHUP: int

De stream werd opgehangen / verbroken. Dit is een ongevraagde gebeurtenis: deze wordt gerapporteerd door poll.poll() / poll.ipoll() zelfs als er niet om werd gevraagd in de eventmask, en het is niet geldig om deze als invoer-eventmask door te geven.

Klassen

class select.poll

Maak een poll-object aan dat een set geregistreerde streams (of willekeurige objecten die het stream-protocol blootstellen) bijhoudt en efficiënt wacht totdat een of meer ervan leesbaar of schrijfbaar wordt, of een uitzonderlijke conditie signaleert.

Streams worden toegevoegd met register(), verwijderd met unregister(), en de set van te observeren gebeurtenissen kan worden gewijzigd met modify(). Eenmaal geconfigureerd, roep poll() aan om te blokkeren totdat er iets gereed is (of een timeout verloopt), of ipoll() voor een allocatievrije, op een iterator gebaseerde variant.

register(obj: Any, eventmask: int = select.POLLIN | select.POLLOUT) → None

Registreer de stream obj voor polling, lettend op de gebeurtenissen gegeven door eventmask (de logische OR van):

eventmask is standaard select.POLLIN | select.POLLOUT.

select.POLLHUP en select.POLLERR zijn niet geldig in een invoer-eventmask – het zijn ongevraagde gebeurtenissen die door poll() / ipoll() worden gerapporteerd, ongeacht of erom werd gevraagd (dit komt overeen met de POSIX-semantiek).

Het is in orde om deze methode meerdere keren aan te roepen voor dezelfde obj: een volgende aanroep werkt de event-mask van obj bij, en gedraagt zich zoals modify().

unregister(obj: Any) → None

Verwijder obj uit de set van geregistreerde streams. Het is geen fout om een obj dat momenteel niet geregistreerd is te deregistreren (de aanroep heeft in dat geval geen effect).

modify(obj: Any, eventmask: int) → None

Wijzig de event-mask voor een reeds geregistreerde obj naar eventmask. Werpt OSError met errno.ENOENT op als obj niet geregistreerd is.

poll(timeout: int = -1, /) → List[Tuple]

Blokkeer totdat ten minste één geregistreerde stream gereed wordt of een uitzonderlijke conditie signaleert, en geef vervolgens de lijst van streams terug die afvuurden.

timeout is de maximale wachttijd in milliseconden. Als deze wordt weggelaten of -1 is, blokkeert de aanroep oneindig; 0 keert onmiddellijk terug (een niet-blokkerende poll).

Geeft een lijst van (obj, event, ...) tuples terug, één per stream die afvuurde. obj is de geregistreerde stream en event is de bitsgewijze OR van de select.POLLIN / select.POLLOUT / select.POLLERR / select.POLLHUP vlaggen die optraden. Elke tuple kan aanvullende implementatie-gedefinieerde elementen bevatten, ga er dus niet van uit dat de lengte exact 2 is. Als timeout verloopt zonder dat er iets gereed is, wordt een lege lijst teruggegeven.

select.POLLHUP en select.POLLERR kunnen op elk moment worden teruggegeven (zelfs als er niet om werd gevraagd) en er moet op worden gereageerd – doorgaans door de betreffende stream te deregistreren en te sluiten – anders blijven volgende aanroepen onmiddellijk terugkeren met deze vlaggen gezet voor die stream.

Het is gegarandeerd dat alle in behandeling zijnde geplande callbacks worden uitgevoerd voordat de polling-lus wordt betreden.

Verschil met CPython

Teruggegeven tuples kunnen meer dan 2 elementen bevatten, zoals hierboven beschreven.

ipoll(timeout: int = -1, flags: int = 0, /) → Iterator[Tuple]

Zoals poll(), maar in plaats van een lijst op te bouwen geeft het een iterator terug die één (obj, event, ...) tuple per keer oplevert. Dit voorkomt allocatie bij elke aanroep, wat belangrijk is voor asynchrone I/O-schedulers.

De opgeleverde tuple is eigendom van de aangeroepene (callee-owned): deze wordt hergebruikt (overschreven) bij de volgende iteratie, dus de inhoud ervan moet binnen het lichaam van de lus worden geconsumeerd en er mogen geen verwijzingen naar worden opgeslagen.

timeout heeft dezelfde betekenis als voor poll(). Als flags 1 is, wordt eenmalig (one-shot) gedrag gebruikt: een stream waarvan de gebeurtenis afvuurde, krijgt zijn event-mask automatisch gewist (equivalent aan poll.modify(obj, 0)), zodat er geen verdere gebeurtenissen voor worden gerapporteerd totdat zijn mask opnieuw wordt gezet met modify().

Het is gegarandeerd dat alle in behandeling zijnde geplande callbacks worden uitgevoerd voordat de polling-lus wordt betreden.

Verschil met CPython

Deze methode is een MicroPython-uitbreiding.