select — Väntar på att I/O ska slutföras

---

Den här modulen ger tillgång till funktionerna select() och poll() som finns i de flesta operativsystem, devpoll() som finns på Solaris och derivat, epoll() som finns på Linux 2.5+ och kqueue() som finns på de flesta BSD. Observera att på Windows fungerar det bara för sockets; på andra operativsystem fungerar det även för andra filtyper (i synnerhet på Unix fungerar det på pipes). Det kan inte användas på vanliga filer för att avgöra om en fil har vuxit sedan den senast lästes.

Anteckning

Modulen selectors möjliggör effektiv I/O-multiplexering på hög nivå och bygger på primitiverna i modulen select. Användare uppmanas att använda modulen selectors i stället, om de inte vill ha exakt kontroll över de primitiver på OS-nivå som används.

Tillgänglighet: not WASI.

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

Modulen definierar följande:

exception select.error

Ett föråldrat alias för OSError.

Ändrad i version 3.3: Efter PEP 3151 gjordes denna klass till ett alias för OSError.

select.devpoll()

(Stöds endast på Solaris och derivat.) Returnerar ett /dev/poll polling-objekt; se avsnitt /dev/poll Polling Objects nedan för de metoder som stöds av devpoll-objekt.

devpoll()-objekt är kopplade till det antal filbeskrivare som är tillåtna vid instantiering. Om ditt program minskar detta värde kommer devpoll() att misslyckas. Om ditt program ökar detta värde kan devpoll() returnera en ofullständig lista över aktiva filbeskrivare.

Den nya filbeskrivaren är icke-ärftlig.

Tillagd i version 3.3.

Ändrad i version 3.4: Den nya filbeskrivaren är nu inte ärftlig.

select.epoll(sizehint=-1, flags=0)

(Stöds endast av Linux 2.5.44 och senare.) Returnerar ett Edge Polling-objekt, som kan användas som Edge- eller Level Triggered-gränssnitt för I/O-händelser.

sizehint informerar epoll om det förväntade antalet händelser som ska registreras. Den måste vara positiv, eller -1 för att använda standardvärdet. Den används endast på äldre system där epoll_create1() inte är tillgänglig; annars har den ingen effekt (även om dess värde fortfarande kontrolleras).

flags är föråldrad och ignoreras helt. Men när den anges måste dess värde vara 0 eller select.EPOLL_CLOEXEC, annars uppstår OSError.

Se avsnittet Objekt för pollning av kant- och nivåtrigger (epoll) nedan för de metoder som stöds av epolling-objekt.

epoll-objekt stöder protokollet för kontexthantering: när de används i en with-sats stängs den nya filbeskrivaren automatiskt i slutet av blocket.

Den nya filbeskrivaren är icke-ärftlig.

Ändrad i version 3.3: Parametern flags har lagts till.

Ändrad i version 3.4: Stöd för with-satsen har lagts till. Den nya filbeskrivaren är nu inte ärftlig.

Föråldrad sedan version 3.4: Parametern flags. select.EPOLL_CLOEXEC används som standard nu. Använd os.set_inheritable() för att göra filbeskrivaren ärftlig.

select.poll()

(Stöds inte av alla operativsystem.) Returnerar ett polling-objekt, som stöder registrering och avregistrering av filbeskrivare och sedan polling av dem för I/O-händelser; se avsnitt Avstämningsobjekt nedan för de metoder som stöds av polling-objekt.

select.kqueue()

(Stöds endast på BSD.) Returnerar ett kernel queue-objekt; se avsnitt Kqueue-objekt nedan för de metoder som stöds av kqueue-objekt.

Den nya filbeskrivaren är icke-ärftlig.

Ändrad i version 3.4: Den nya filbeskrivaren är nu inte ärftlig.

select.kevent(ident, filter=KQ_FILTER_READ, flags=KQ_EV_ADD, fflags=0, data=0, udata=0)

(Stöds endast på BSD.) Returnerar ett kernel event-objekt; se avsnitt Kevent-objekt nedan för de metoder som stöds av kevent-objekt.

select.select(rlist, wlist, xlist[, timeout])

Detta är ett enkelt gränssnitt till Unix select() systemanrop. De tre första argumenten är iterabler av ”väntande objekt”: antingen heltal som representerar filbeskrivare eller objekt med en parameterlös metod med namnet fileno() som returnerar ett sådant heltal:

• rlist: vänta tills den är klar för läsning

• wlist: vänta tills den är klar för skrivning

• xlist: vänta på ett ”exceptionellt tillstånd” (se manualsidan för vad ditt system anser vara ett sådant tillstånd)

Tomma iterabler är tillåtna, men acceptansen av tre tomma iterabler är plattformsberoende. (Det är känt att den fungerar på Unix men inte på Windows.) Det valfria argumentet timeout anger en timeout som ett flyttal i sekunder. När argumentet timeout utelämnas blockerar funktionen tills minst en filbeskrivare är klar. Ett timeout-värde på noll anger en poll och blockerar aldrig.

Returvärdet är en trippel av listor med objekt som är klara: delmängder av de tre första argumenten. När tidsgränsen nås utan att en filbeskrivare har blivit klar returneras tre tomma listor.

Bland de acceptabla objekttyperna i iterablerna finns Python filobjekt (t.ex. sys.stdin, eller objekt som returneras av open() eller os.popen()), socketobjekt som returneras av socket.socket(). Du kan också definiera en wrapper-klass själv, så länge den har en lämplig fileno()-metod (som verkligen returnerar en filbeskrivare, inte bara ett slumpmässigt heltal).

Anteckning

Filobjekt på Windows är inte acceptabla, men sockets är det. I Windows tillhandahålls den underliggande funktionen select() av WinSock-biblioteket och hanterar inte filbeskrivare som inte kommer från WinSock.

Ändrad i version 3.5: Funktionen försöker nu igen med en omräknad timeout när den avbryts av en signal, utom om signalhanteraren gör ett undantag (se PEP 475 för motiveringen), istället för att göra InterruptedError.

select.PIPE_BUF

Det minsta antalet byte som kan skrivas utan blockering till en pipe när pipen har rapporterats som klar för skrivning av select(), poll() eller ett annat gränssnitt i denna modul. Detta gäller inte för andra filliknande objekt som t.ex. sockets.

Detta värde är garanterat av POSIX att vara minst 512.

Tillgänglighet: Unix

Tillagd i version 3.2.

/dev/poll Polling Objects

Solaris och dess derivat har /dev/poll. Medan select() är O(högsta filbeskrivare) och poll() är O(antal filbeskrivare), är /dev/poll O(aktiva filbeskrivare).

/dev/poll beteende är mycket nära standard poll() objektet.

devpoll.close()

Stäng fildeskriptorn för polling-objektet.

Tillagd i version 3.4.

devpoll.closed

True om polling-objektet är stängt.

Tillagd i version 3.4.

devpoll.fileno()

Returnera filbeskrivningsnumret för polling-objektet.

Tillagd i version 3.4.

devpoll.register(fd[, eventmask])

Registrera en filbeskrivare med polling-objektet. Framtida anrop till metoden poll() kommer sedan att kontrollera om filbeskrivaren har några väntande I/O-händelser. fd kan antingen vara ett heltal eller ett objekt med en fileno()-metod som returnerar ett heltal. Filobjekt implementerar fileno(), så de kan också användas som argument.

eventmask är en valfri bitmask som beskriver vilken typ av händelser du vill söka efter. Konstanterna är desamma som för objektet poll(). Standardvärdet är en kombination av konstanterna POLLIN, POLLPRI och POLLOUT.

Varning

Att registrera en filbeskrivare som redan är registrerad är inte ett fel, men resultatet är odefinierat. Den lämpliga åtgärden är att avregistrera eller modifiera den först. Detta är en viktig skillnad jämfört med poll().

devpoll.modify(fd[, eventmask])

Denna metod gör en unregister() följt av en register(). Det är (lite) mer effektivt än att göra samma sak explicit.

devpoll.unregister(fd)

Ta bort en filbeskrivare som spåras av ett polling-objekt. Precis som metoden register() kan fd vara ett heltal eller ett objekt med en metod fileno() som returnerar ett heltal.

Försök att ta bort en filbeskrivning som aldrig registrerats ignoreras på ett säkert sätt.

devpoll.poll([timeout])

Undersöker uppsättningen av registrerade filbeskrivare och returnerar en eventuellt tom lista som innehåller (fd, event) 2-tuples för de beskrivare som har händelser eller fel att rapportera. fd är filbeskrivaren, och event är en bitmask med bitar inställda för de rapporterade händelserna för den beskrivaren — POLLIN för väntande inmatning, POLLOUT för att ange att beskrivaren kan skrivas till, och så vidare. En tom lista indikerar att anropet timade ut och att inga filbeskrivare hade några händelser att rapportera. Om timeout anges, specificeras den tid i millisekunder som systemet ska vänta på händelser innan det återvänder. Om timeout utelämnas, -1, eller None, kommer anropet att blockeras tills det finns en händelse för detta poll-objekt.

Ändrad i version 3.5: Funktionen försöker nu igen med en omräknad timeout när den avbryts av en signal, utom om signalhanteraren gör ett undantag (se PEP 475 för motiveringen), istället för att göra InterruptedError.

Objekt för pollning av kant- och nivåtrigger (epoll)

https://linux.die.net/man/4/epoll

eventmask

Konstant	Betydelse
EPOLLIN	Tillgänglig för läsning
EPOLLOUT	Tillgänglig för skrivning
EPOLLPRI	Brådskande data för läsning
EPOLLERR	Feltillstånd inträffade på assoc. fd
EPOLLHUP	Lägg på luren hände på assoc. fd
EPOLLET	Ställ in Edge Trigger-beteende, standard är Level Trigger-beteende
EPOLLONESHOT	Ställ in one-shot-beteende. Efter att en händelse har dragits ut är fd internt inaktiverad
EPOLLEXCLUSIVE	Väck bara ett epoll-objekt när den associerade fd:n har en händelse. Standardinställningen (om denna flagga inte är inställd) är att väcka alla epoll-objekt som pollar på en fd.
EPOLLRDHUP	Stream socket peer stängde anslutningen eller stängde av skrivande halva av anslutningen.
EPOLLRDNORM	Motsvarar EPOLLIN
EPOLLRDBAND	Prioriterat databand kan läsas.
EPOLLWRNORM	Motsvarar EPOLLOUT
EPOLLWRBAND	Prioriterad data kan skrivas.
EPOLLMSG	Ignorerad.
EPOLLWAKEUP	Förhindrar sömn under väntan på händelse.

Tillagd i version 3.6: EPOLLEXCLUSIVE lades till. Det stöds endast av Linux Kernel 4.5 eller senare.

Tillagd i version 3.14: EPOLLWAKEUP har lagts till. Det stöds endast av Linux Kernel 3.5 eller senare.

epoll.close()

Stäng kontrollfilens deskriptor för epoll-objektet.

epoll.closed

True om epoll-objektet är stängt.

epoll.fileno()

Returnera filbeskrivningsnumret för kontrollen fd.

epoll.fromfd(fd)

Skapa ett epoll-objekt från en given filbeskrivare.

epoll.register(fd[, eventmask])

Registrera en fd-descriptor med epoll-objektet.

epoll.modify(fd, eventmask)

Ändra en registrerad filbeskrivare.

epoll.unregister(fd)

Ta bort en registrerad filbeskrivare från epoll-objektet.

Ändrad i version 3.9: Metoden ignorerar inte längre EBADF-felet.

epoll.poll(timeout=None, maxevents=-1)

Vänta på händelser. timeout i sekunder (float)

Ändrad i version 3.5: Funktionen försöker nu igen med en omräknad timeout när den avbryts av en signal, utom om signalhanteraren gör ett undantag (se PEP 475 för motiveringen), istället för att göra InterruptedError.

Avstämningsobjekt

Systemanropet poll(), som stöds av de flesta Unix-system, ger bättre skalbarhet för nätverksservrar som betjänar många, många klienter samtidigt. poll() skalar bättre eftersom systemanropet bara behöver lista de filbeskrivare som är av intresse, medan select() bygger upp en bitmapp, slår på bitar för de intressanta filerna och sedan måste hela bitmappen skannas linjärt igen. select() är O(högsta filbeskrivare), medan poll() är O(antal filbeskrivare).

poll.register(fd[, eventmask])

Registrera en filbeskrivare med polling-objektet. Framtida anrop till metoden poll() kommer sedan att kontrollera om filbeskrivaren har några väntande I/O-händelser. fd kan antingen vara ett heltal eller ett objekt med en fileno()-metod som returnerar ett heltal. Filobjekt implementerar fileno(), så de kan också användas som argument.

eventmask är en valfri bitmask som beskriver vilken typ av händelser du vill kontrollera för och kan vara en kombination av konstanterna POLLIN, POLLPRI och POLLOUT, som beskrivs i tabellen nedan. Om inget anges kommer standardvärdet att användas för att kontrollera alla 3 typerna av händelser.

Konstant	Betydelse
POLLIN	Det finns data att läsa
POLLPRI	Det finns brådskande uppgifter att läsa
POLLOUT	Klar för utmatning: skrivning blockeras inte
POLLERR	Feltillstånd av något slag
POLLHUP	Hängde upp
POLLRDHUP	Stream socket peer stängde anslutningen, eller stängde av skrivande halva av anslutningen
POLLNVAL	Ogiltig begäran: descriptorn är inte öppen

Att registrera en filbeskrivare som redan är registrerad är inte ett fel, och har samma effekt som att registrera beskrivaren exakt en gång.

poll.modify(fd, eventmask)

Ändrar en redan registrerad fd. Detta har samma effekt som register(fd, eventmask). Försök att modifiera en filbeskrivare som aldrig registrerats orsakar ett OSError undantag med errno ENOENT.

poll.unregister(fd)

Ta bort en filbeskrivare som spåras av ett polling-objekt. Precis som metoden register() kan fd vara ett heltal eller ett objekt med en metod fileno() som returnerar ett heltal.

Försök att ta bort en filbeskrivare som aldrig registrerats orsakar ett KeyError undantag.

poll.poll([timeout])

Undersöker uppsättningen av registrerade filbeskrivare och returnerar en eventuellt tom lista som innehåller (fd, event) 2-tuples för de beskrivare som har händelser eller fel att rapportera. fd är filbeskrivaren, och event är en bitmask med bitar inställda för de rapporterade händelserna för den beskrivaren — POLLIN för väntande inmatning, POLLOUT för att ange att beskrivaren kan skrivas till, och så vidare. En tom lista indikerar att anropet timade ut och att inga filbeskrivare hade några händelser att rapportera. Om timeout anges, specificeras den tid i millisekunder som systemet ska vänta på händelser innan det återvänder. Om timeout utelämnas, är negativ eller None, kommer anropet att blockeras tills det finns en händelse för detta poll-objekt.

Ändrad i version 3.5: Funktionen försöker nu igen med en omräknad timeout när den avbryts av en signal, utom om signalhanteraren gör ett undantag (se PEP 475 för motiveringen), istället för att göra InterruptedError.

Kqueue-objekt

kqueue.close()

Stäng kontrollfilens deskriptor för kqueue-objektet.

kqueue.closed

True om kqueue-objektet är stängt.

kqueue.fileno()

Returnera filbeskrivningsnumret för kontrollen fd.

kqueue.fromfd(fd)

Skapa ett kqueue-objekt från en given filbeskrivning.

kqueue.control(changelist, max_events[, timeout]) → eventlist

Lågnivågränssnitt till kevent

• changelist måste vara en iterabel av kevent-objekt eller None

• max_events måste vara 0 eller ett positivt heltal

• timeout i sekunder (flytande värden är möjliga); standardvärdet är None, att vänta för evigt

Ändrad i version 3.5: Funktionen försöker nu igen med en omräknad timeout när den avbryts av en signal, utom om signalhanteraren gör ett undantag (se PEP 475 för motiveringen), istället för att göra InterruptedError.

Kevent-objekt

https://man.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2

kevent.ident

Värde som används för att identifiera händelsen. Tolkningen beror på filtret men det är vanligtvis filbeskrivaren. I konstruktorn kan ident antingen vara en int eller ett objekt med en fileno()-metod. kevent lagrar heltalet internt.

kevent.filter

Namn på kernelfiltret.

Konstant	Betydelse
KQ_FILTER_READ	Tar en descriptor och returnerar när det finns data tillgängliga att läsa
KQ_FILTER_WRITE	Tar en descriptor och returnerar när det finns data tillgängliga att skriva
KQ_FILTER_AIO	AIO-förfrågningar
KQ_FILTER_VNODE	Returnerar när en eller flera av de begärda händelserna som bevakas i fflag inträffar
KQ_FILTER_PROC	Se efter händelser på ett process-ID
KQ_FILTER_NETDEV	Håll utkik efter händelser på en nätverksenhet [inte tillgängligt på macOS]
KQ_FILTER_SIGNAL	Returnerar när den bevakade signalen levereras till processen
KQ_FILTER_TIMER	Upprättar en godtycklig timer

kevent.flags

Filteråtgärd.

Konstant	Betydelse
KQ_EV_ADD	Lägger till eller ändrar en händelse
KQ_EV_DELETE	Tar bort en händelse från kön
KQ_EV_ENABLE	Tillåtercontrol() att returnera händelsen
KQ_EV_DISABLE	Avaktiverar händelse
KQ_EV_ONESHOT	Tar bort händelse efter första förekomsten
KQ_EV_CLEAR	Återställ tillståndet efter att en händelse har hämtats
KQ_EV_SYSFLAGS	intern händelse
KQ_EV_FLAG1	intern händelse
KQ_EV_EOF	Filterspecifikt EOF-tillstånd
KQ_EV_ERROR	Se returvärden

kevent.fflags

Filtrera specifika flaggor.

KQ_FILTER_READ och KQ_FILTER_WRITE filterflaggor:

Konstant	Betydelse
KQ_NOTE_LOWAT	lågvattenmärke för en socketbuffert

KQ_FILTER_VNODE filterflaggor:

Konstant	Betydelse
KQ_NOTE_DELETE	unlink() anropades
KQ_NOTE_WRITE	en skrivning inträffade
KQ_NOTE_EXTEND	filen förlängdes
KQ_NOTE_ATTRIB	ett attribut har ändrats
KQ_NOTE_LINK	länkantalet har ändrats
KQ_NOTE_RENAME	filen döptes om
KQ_NOTE_REVOKE	åtkomst till filen återkallades

KQ_FILTER_PROC filterflaggor:

Konstant	Betydelse
KQ_NOTE_EXIT	processen har avslutats
KQ_NOTE_FORK	processen har anropat fork()
KQ_NOTE_EXEC	processen har exekverat en ny process
KQ_NOTE_PCTRLMASK	intern filterflagga
KQ_NOTE_PDATAMASK	intern filterflagga
KQ_NOTE_TRACK	följa en process över fork()
KQ_NOTE_CHILD	returneras på barnprocessen för NOTE_TRACK
KQ_NOTE_TRACKERR	inte kan knyta an till ett barn

KQ_FILTER_NETDEV filterflaggor (inte tillgängligt på macOS):

Konstant	Betydelse
KQ_NOTE_LINKUP	länken är uppe
KQ_NOTE_LINKDOWN	länken är nere
KQ_NOTE_LINKINV	länkstatus är ogiltig

kevent.data

Filtrera specifika data.

kevent.udata

Användardefinierat värde.