Initialisering, slutförande och trådar

Se Python Initialization Configuration för detaljer om hur man konfigurerar tolken före initialiseringen.

Före initialisering av Python

I ett program som innehåller Python måste funktionen Py_Initialize() anropas innan några andra Python/C API-funktioner används, med undantag för några få funktioner och globala konfigurationsvariabler.

Följande funktioner kan anropas innan Python har initialiserats:

Anteckning

Trots deras uppenbara likhet med några av de funktioner som listas ovan, bör följande funktioner inte anropas innan tolken har initialiserats: Py_EncodeLocale(), Py_GetPath(), Py_GetPrefix(), Py_GetExecPrefix(), Py_GetProgramFullPath(), Py_GetPythonHome(), Py_GetProgramName(), PyEval_InitThreads(), och Py_RunMain().

Variabler för global konfiguration

Python har variabler för den globala konfigurationen för att styra olika funktioner och alternativ. Som standard styrs dessa flaggor av kommandoradsalternativ.

När en flagga anges av ett alternativ är flaggans värde det antal gånger som alternativet har angetts. Till exempel sätter -b Py_BytesWarningFlag till 1 och -bb sätter Py_BytesWarningFlag till 2.

int Py_BytesWarningFlag

Detta API behålls för bakåtkompatibilitet: inställningen PyConfig.bytes_warning bör användas istället, se Python Initialization Configuration.

Utfärda en varning när du jämför bytes eller bytearray med str eller bytes med int. Utfärda ett fel om det är större än eller lika med 2.

Ställs in av alternativet -b.

Deprecated since version 3.12, will be removed in version 3.15.

int Py_DebugFlag

Detta API behålls för bakåtkompatibilitet: inställningen PyConfig.parser_debug bör användas istället, se Python Initialization Configuration.

Aktivera felsökningsutmatning för parser (endast för experter, beroende på kompileringsalternativ).

Ställs in av alternativet -d och miljövariabeln PYTHONDEBUG.

Deprecated since version 3.12, will be removed in version 3.15.

int Py_DontWriteBytecodeFlag

Detta API behålls för bakåtkompatibilitet: inställning PyConfig.write_bytecode bör användas istället, se Python Initialization Configuration.

Om den är satt till icke-noll kommer Python inte att försöka skriva .pyc -filer vid import av källmoduler.

Ställs in av alternativet -B och miljövariabeln PYTHONDONTWRITEBYTECODE.

Deprecated since version 3.12, will be removed in version 3.15.

int Py_FrozenFlag

Detta API behålls för bakåtkompatibilitet: inställningen PyConfig.pathconfig_warnings bör användas istället, se Python Initialization Configuration.

Undertrycker felmeddelanden vid beräkning av modulens sökväg i Py_GetPath().

Privat flagga som används av programmen _freeze_module och frozenmain.

Deprecated since version 3.12, will be removed in version 3.15.

int Py_HashRandomizationFlag

Detta API behålls för bakåtkompatibilitet: inställningarna PyConfig.hash_seed och PyConfig.use_hash_seed bör användas istället, se Python Initialization Configuration.

Sätts till 1 om miljövariabeln PYTHONHASHSEED är satt till en icke-tom sträng.

Om flaggan inte är noll, läs miljövariabeln PYTHONHASHSEED för att initiera det hemliga hashfröet.

Deprecated since version 3.12, will be removed in version 3.15.

int Py_IgnoreEnvironmentFlag

Detta API behålls för bakåtkompatibilitet: inställningen PyConfig.use_environment bör användas istället, se Python Initialization Configuration.

Ignorera alla PYTHON* miljövariabler, t.ex. PYTHONPATH och PYTHONHOME, som kan vara inställda.

Ställs in av alternativen -E och -I.

Deprecated since version 3.12, will be removed in version 3.15.

int Py_InspectFlag

Detta API behålls för bakåtkompatibilitet: inställningen PyConfig.inspect bör användas istället, se Python Initialization Configuration.

När ett skript anges som första argument eller alternativet -c används, gå till interaktivt läge efter att skriptet eller kommandot har exekverats, även om sys.stdin inte verkar vara en terminal.

Ställs in av alternativet -i och miljövariabeln PYTHONINSPECT.

Deprecated since version 3.12, will be removed in version 3.15.

int Py_InteractiveFlag

Detta API behålls för bakåtkompatibilitet: inställning PyConfig.interactive bör användas istället, se Python Initialization Configuration.

Ställs in av alternativet -i.

Deprecated since version 3.12, will be removed in version 3.15.

int Py_IsolatedFlag

Detta API behålls för bakåtkompatibilitet: inställningen PyConfig.isolated bör användas istället, se Python Initialization Configuration.

Kör Python i isolerat läge. I isolerat läge innehåller sys.path varken skriptets katalog eller användarens site-packages-katalog.

Ställs in av alternativet -I.

Tillagd i version 3.4.

Deprecated since version 3.12, will be removed in version 3.15.

int Py_LegacyWindowsFSEncodingFlag

Detta API behålls för bakåtkompatibilitet: inställningen PyPreConfig.legacy_windows_fs_encoding bör användas istället, se Python Initialization Configuration.

Om flaggan är annan än noll, använd kodningen mbcs med felhanteraren replace istället för UTF-8-kodningen med felhanteraren surrogatepass för filesystem encoding and error handler.

Sätts till 1 om miljövariabeln PYTHONLEGACYWINDOWSFSENCODING är satt till en icke-tom sträng.

Se PEP 529 för mer information.

Tillgänglighet: Windows.

Deprecated since version 3.12, will be removed in version 3.15.

int Py_LegacyWindowsStdioFlag

Detta API behålls för bakåtkompatibilitet: inställning PyConfig.legacy_windows_stdio bör användas istället, se Python Initialization Configuration.

Om flaggan inte är noll, använd io.FileIO istället för io._WindowsConsoleIO för sys standardströmmar.

Sätts till 1 om miljövariabeln PYTHONLEGACYWINDOWSSTDIO är satt till en icke-tom sträng.

Se PEP 528 för mer information.

Tillgänglighet: Windows.

Deprecated since version 3.12, will be removed in version 3.15.

int Py_NoSiteFlag

Detta API behålls för bakåtkompatibilitet: inställningen PyConfig.site_import bör användas istället, se Python Initialization Configuration.

Inaktivera importen av modulen site och de platsberoende manipuleringarna av sys.path som den medför. Inaktivera även dessa manipuleringar om site uttryckligen importeras senare (anropa site.main() om du vill att de ska utlösas).

Ställs in av alternativet -S.

Deprecated since version 3.12, will be removed in version 3.15.

int Py_NoUserSiteDirectory

Detta API behålls för bakåtkompatibilitet: inställningen PyConfig.user_site_directory bör användas istället, se Python Initialization Configuration.

Lägg inte till katalogen user site-packages i sys.path.

Ställs in av alternativen -s och -I samt miljövariabeln PYTHONNOUSERSITE.

Deprecated since version 3.12, will be removed in version 3.15.

int Py_OptimizeFlag

Detta API behålls för bakåtkompatibilitet: inställningen PyConfig.optimization_level bör användas istället, se Python Initialization Configuration.

Ställs in av alternativet -O och miljövariabeln PYTHONOPTIMIZE.

Deprecated since version 3.12, will be removed in version 3.15.

int Py_QuietFlag

Detta API behålls för bakåtkompatibilitet: inställningen PyConfig.quiet bör användas istället, se Python Initialization Configuration.

Visa inte copyright- och versionsmeddelanden ens i interaktivt läge.

Ställs in av alternativet -q.

Tillagd i version 3.2.

Deprecated since version 3.12, will be removed in version 3.15.

int Py_UnbufferedStdioFlag

Detta API behålls för bakåtkompatibilitet: inställning PyConfig.buffered_stdio bör användas istället, se Python Initialization Configuration.

Tvinga stdout- och stderr-strömmarna att vara obuffrade.

Ställs in av alternativet -u och miljövariabeln PYTHONUNBUFFERED.

Deprecated since version 3.12, will be removed in version 3.15.

int Py_VerboseFlag

Detta API behålls för bakåtkompatibilitet: inställningen PyConfig.verbose bör användas istället, se Python Initialization Configuration.

Varje gång en modul initieras skrivs ett meddelande ut som visar varifrån den laddats (filnamn eller inbyggd modul). Om värdet är större än eller lika med 2, skrivs ett meddelande ut för varje fil som kontrolleras vid sökning efter en modul. Ger också information om modulrensning vid avslutning.

Ställs in av alternativet -v och miljövariabeln PYTHONVERBOSE.

Deprecated since version 3.12, will be removed in version 3.15.

Initialisering och slutbehandling av tolken

void Py_Initialize()
En del av Stabil ABI.

Initialiserar Python-tolken. I ett program som bäddar in Python bör detta anropas innan du använder några andra Python/C API-funktioner; se För Python-initialisering för de få undantagen.

Detta initierar tabellen över inlästa moduler (sys.modules) och skapar de grundläggande modulerna builtins, __main__ och sys. Den initialiserar också sökvägen för modulerna (sys.path). Den ställer inte in sys.argv; använd Python Initialization Configuration API för det. Detta är en no-op när den anropas en andra gång (utan att anropa Py_FinalizeEx() först). Det finns inget returvärde; det är ett fatalt fel om initialiseringen misslyckas.

Använd Py_InitializeFromConfig() för att anpassa Python Initialization Configuration.

Anteckning

I Windows ändras konsolläget från O_TEXT till O_BINARY, vilket också påverkar konsolanvändning som inte är Python och som använder C Runtime.

void Py_InitializeEx(int initsigs)
En del av Stabil ABI.

Denna funktion fungerar som Py_Initialize() om initsigs är 1. Om initsigs är 0 hoppar den över initialiseringsregistreringen av signalhanterare, vilket kan vara användbart när CPython är inbäddat som en del av ett större program.

Använd Py_InitializeFromConfig() för att anpassa Python Initialization Configuration.

PyStatus Py_InitializeFromConfig(const PyConfig *config)

Initiera Python från config-konfigurationen, enligt beskrivningen i Initialisering med PyConfig.

Se avsnittet Konfiguration av Python-initialisering för mer information om hur du förinitierar tolken, fyller i konfigurationsstrukturen för körtid och frågar efter den returnerade statusstrukturen.

int Py_IsInitialized()
En del av Stabil ABI.

Returnerar true (icke-noll) när Python-tolken har initialiserats, false (noll) om så inte är fallet. Efter anrop av Py_FinalizeEx() returneras false tills Py_Initialize() anropas igen.

int Py_IsFinalizing()
En del av Stabil ABI sedan version 3.13.

Returnerar true (icke-noll) om Pythons huvudtolk stänger ner. Returnerar false (noll) annars.

Tillagd i version 3.13.

int Py_FinalizeEx()
En del av Stabil ABI sedan version 3.6.

Ångra alla initialiseringar som gjorts av Py_Initialize() och efterföljande användning av Python/C API-funktioner, och förstör alla undertolkare (se Py_NewInterpreter() nedan) som skapats och ännu inte förstörts sedan det senaste anropet till Py_Initialize(). Detta är ett no-op när det anropas en andra gång (utan att först anropa Py_Initialize() igen).

Eftersom detta är det omvända av Py_Initialize(), bör det anropas i samma tråd med samma tolk aktiv. Det betyder huvudtråden och huvudtolken. Detta bör aldrig anropas medan Py_RunMain() körs.

Normalt är returvärdet 0. Om det uppstod fel under slutförandet (rensning av buffrade data) returneras -1.

Observera att Python kommer att göra sitt bästa för att frigöra allt minne som allokerats av Python-tolken. Därför bör alla C-tillägg se till att korrekt städa upp alla tidigare allokerade PyObjects innan de används i efterföljande anrop till Py_Initialize(). Annars kan det introducera sårbarheter och felaktigt beteende.

Denna funktion tillhandahålls av ett antal skäl. Ett inbäddningsprogram kanske vill starta om Python utan att behöva starta om programmet självt. En applikation som har laddat Python-tolken från ett dynamiskt laddningsbart bibliotek (eller DLL) kanske vill frigöra allt minne som allokerats av Python innan DLL:en avlastas. Under en jakt på minnesläckor i en applikation kan en utvecklare vilja frigöra allt minne som allokerats av Python innan applikationen avslutas.

Buggar och förbehåll: Destruktionen av moduler och objekt i moduler sker i slumpmässig ordning; detta kan leda till att destruktorer (__del__() metoder) misslyckas när de är beroende av andra objekt (även funktioner) eller moduler. Dynamiskt laddade tilläggsmoduler som laddats av Python avlastas inte. Små mängder minne som allokerats av Python-tolken kanske inte frigörs (om du hittar en läcka, rapportera den). Minne som är bundet i cirkulära referenser mellan objekt frigörs inte. Internerade strängar kommer alla att avallokeras oavsett deras referensantal. En del minne som allokeras av tilläggsmoduler kanske inte frigörs. Vissa tillägg kanske inte fungerar korrekt om deras initialiseringsrutin anropas mer än en gång; detta kan hända om ett program anropar Py_Initialize() och Py_FinalizeEx() mer än en gång. Py_FinalizeEx() får inte anropas rekursivt inifrån sig själv. Därför får den inte anropas av någon kod som kan köras som en del av tolkens avstängningsprocess, t.ex. atexit-hanterare, objektavslutare eller någon kod som kan köras medan filerna stdout och stderr rensas.

Utlöser en auditing event cpython._PySys_ClearAuditHooks utan argument.

Tillagd i version 3.6.

void Py_Finalize()
En del av Stabil ABI.

Detta är en bakåtkompatibel version av Py_FinalizeEx() som bortser från returvärdet.

int Py_BytesMain(int argc, char **argv)
En del av Stabil ABI sedan version 3.8.

Liknar Py_Main() men argv är en array av bytessträngar, vilket gör att den anropande applikationen kan delegera textavkodningssteget till CPython-körtiden.

Tillagd i version 3.8.

int Py_Main(int argc, wchar_t **argv)
En del av Stabil ABI.

Huvudprogrammet för standardtolken, som innehåller en fullständig initialiserings-/avslutningscykel samt ytterligare beteende för att läsa konfigurationsinställningar från miljön och kommandoraden och sedan köra __main__ i enlighet med Kommandorad.

Detta görs tillgängligt för program som vill stödja hela CPythons kommandoradsgränssnitt, snarare än att bara bädda in en Python-körtid i en större applikation.

Parametrarna argc och argv liknar dem som skickas till ett C-programs funktion main(), förutom att argv-posterna först konverteras till wchar_t med hjälp av Py_DecodeLocale(). Det är också viktigt att notera att posterna i argumentlistan kan ändras så att de pekar på andra strängar än de som skickas in (innehållet i de strängar som argumentlistan pekar på ändras dock inte).

Returvärdet är 2 om argumentlistan inte representerar en giltig Python-kommandorad, och i övrigt samma som Py_RunMain().

När det gäller CPython-runtime-konfigurations-API:er som dokumenteras i avsnittet runtime configuration (och utan hänsyn till felhantering) är Py_Main ungefär likvärdigt med:

PyConfig config;
PyConfig_InitPythonConfig(&config);
PyConfig_SetArgv(&config, argc, argv);
Py_InitializeFromConfig(&config);
PyConfig_Clear(&config);

Py_RunMain();

Vid normal användning kommer ett inbäddningsprogram att anropa den här funktionen i stället för att anropa Py_Initialize(), Py_InitializeEx() eller Py_InitializeFromConfig() direkt, och alla inställningar kommer att tillämpas enligt beskrivningen på andra ställen i den här dokumentationen. Om denna funktion istället anropas efter ett föregående API-anrop för initiering av körtiden, är exakt vilka miljö- och kommandoradsinställningar som uppdateras versionsberoende (eftersom det beror på vilka inställningar som korrekt stöder att de ändras efter att de redan har ställts in en gång när körtiden initierades första gången).

int Py_RunMain(void)

Exekverar huvudmodulen i en fullt konfigurerad CPython-körtid.

Utför kommandot (PyConfig.run_command), skriptet (PyConfig.run_filename) eller modulen (PyConfig.run_module) som anges på kommandoraden eller i konfigurationen. Om inget av dessa värden har angetts körs den interaktiva Python-prompten (REPL) med hjälp av modulen __main__ globala namnrymd.

Om PyConfig.inspect inte är inställd (standard), kommer returvärdet att vara 0 om tolken avslutas normalt (dvs. utan att ett undantag uppstår), utgångsstatus för ett ohanterat SystemExit, eller 1 för något annat ohanterat undantag.

Om PyConfig.inspect är inställt (t.ex. när alternativet -i används), i stället för att återvända när tolken avslutas, kommer exekveringen i stället att återupptas i en interaktiv Python-prompt (REPL) som använder modulen __main__’s globala namnrymd. Om tolken avslutades med ett undantag, tas det omedelbart upp i REPL-sessionen. Funktionens returvärde bestäms sedan av hur REPL-sessionen avslutas: 0, 1, eller statusen för en SystemExit, enligt specifikationen ovan.

Denna funktion slutför alltid Python-tolken innan den returneras.

Se Python Configuration för ett exempel på en anpassad Python som alltid körs i isolerat läge med Py_RunMain().

int PyUnstable_AtExit(PyInterpreterState *interp, void (*func)(void*), void *data)
Detta är Instabilt API. Den kan ändras utan förvarning i mindre versioner.

Registrera en atexit callback för måltolken interp. Detta liknar Py_AtExit(), men tar en explicit tolk och datapekare för återuppringningen.

Det måste finnas en attached thread state för interp.

Tillagd i version 3.13.

Processövergripande parametrar

void Py_SetProgramName(const wchar_t *name)
En del av Stabil ABI.

Detta API behålls för bakåtkompatibilitet: inställningen PyConfig.program_name bör användas istället, se Python Initialization Configuration.

Denna funktion bör anropas innan Py_Initialize() anropas för första gången, om den anropas överhuvudtaget. Den talar om för tolken värdet på argumentet argv[0] till funktionen main() i programmet (konverterat till breda tecken). Detta används av Py_GetPath() och några andra funktioner nedan för att hitta Pythons körtidsbibliotek i förhållande till tolkens körbara fil. Standardvärdet är 'python'. Argumentet ska peka på en nollavslutad bred teckensträng i statisk lagring vars innehåll inte kommer att ändras under programmets exekvering. Ingen kod i Python-tolken kommer att ändra innehållet i denna lagring.

Använd Py_DecodeLocale() för att avkoda en bytes-sträng för att få en wchar_t*-sträng.

Deprecated since version 3.11, will be removed in version 3.15.

wchar_t *Py_GetProgramName()
En del av Stabil ABI.

Returnerar det programnamn som ställts in med PyConfig.program_name, eller standardvärdet. Den returnerade strängen pekar in i statisk lagring; anroparen bör inte ändra dess värde.

Denna funktion bör inte anropas före Py_Initialize(), annars returnerar den NULL.

Ändrad i version 3.10: Den returnerar nu NULL om den anropas före Py_Initialize().

Deprecated since version 3.13, will be removed in version 3.15: Använd PyConfig_Get("executable") (sys.executable) istället.

wchar_t *Py_GetPrefix()
En del av Stabil ABI.

Returnerar prefixet för installerade plattformsoberoende filer. Detta härleds genom ett antal komplicerade regler från det programnamn som anges med PyConfig.program_name och vissa miljövariabler; till exempel, om programnamnet är '/usr/local/bin/python', är prefixet '/usr/local'. Den returnerade strängen pekar in i statisk lagring; anroparen ska inte ändra dess värde. Detta motsvarar variabeln prefix i toppnivån Makefile och argumentet --prefix till skriptet configure vid byggtiden. Värdet är tillgängligt för Python-kod som sys.base_prefix. Det är endast användbart på Unix. Se även nästa funktion.

Denna funktion bör inte anropas före Py_Initialize(), annars returnerar den NULL.

Ändrad i version 3.10: Den returnerar nu NULL om den anropas före Py_Initialize().

Deprecated since version 3.13, will be removed in version 3.15: Använd PyConfig_Get("base_prefix") (sys.base_prefix) istället. Använd PyConfig_Get("prefix") (sys.prefix) om virtuella miljöer behöver hanteras.

wchar_t *Py_GetExecPrefix()
En del av Stabil ABI.

Returnerar exec-prefixet för installerade plattformsberoende* filer. Detta härleds genom ett antal komplicerade regler från det programnamn som anges med PyConfig.program_name och vissa miljövariabler; till exempel, om programnamnet är '/usr/local/bin/python', är exec-prefixet '/usr/local'. Den returnerade strängen pekar in i statisk lagring; anroparen ska inte ändra dess värde. Detta motsvarar variabeln exec_prefix i toppnivån Makefile och argumentet --exec-prefix till skriptet configure vid byggtiden. Värdet är tillgängligt för Python-kod som sys.base_exec_prefix. Det är endast användbart på Unix.

Bakgrund: Exec-prefixet skiljer sig från prefixet när plattformsberoende filer (t.ex. körbara filer och delade bibliotek) installeras i ett annat katalogträd. I en typisk installation kan plattformsberoende filer installeras i underträdet /usr/local/plat medan plattformsoberoende kan installeras i /usr/local.

Generellt sett är en plattform en kombination av maskinvaru- och programvarufamiljer, t.ex. Sparc-maskiner som kör operativsystemet Solaris 2.x betraktas som samma plattform, men Intel-maskiner som kör Solaris 2.x är en annan plattform och Intel-maskiner som kör Linux är ytterligare en annan plattform. Olika större revisioner av samma operativsystem utgör i allmänhet också olika plattformar. Icke-Unix-operativsystem är en annan historia; installationsstrategierna på dessa system är så olika att prefixet och exec-prefixet är meningslösa och sätts till den tomma strängen. Observera att kompilerade Python-bytekodfiler är plattformsoberoende (men inte oberoende av den Python-version som de kompilerades med!)

Systemadministratörer kommer att veta hur man konfigurerar programmen mount eller automount för att dela /usr/local mellan plattformar samtidigt som /usr/local/plat är ett annat filsystem för varje plattform.

Denna funktion bör inte anropas före Py_Initialize(), annars returnerar den NULL.

Ändrad i version 3.10: Den returnerar nu NULL om den anropas före Py_Initialize().

Deprecated since version 3.13, will be removed in version 3.15: Använd PyConfig_Get("base_exec_prefix") (sys.base_exec_prefix) istället. Använd PyConfig_Get("exec_prefix") (sys.exec_prefix) om virtuella miljöer behöver hanteras.

wchar_t *Py_GetProgramFullPath()
En del av Stabil ABI.

Returnerar det fullständiga programnamnet för den körbara Python-filen; detta beräknas som en bieffekt av att standardmodulsökvägen härleds från programnamnet (anges av PyConfig.program_name). Den returnerade strängen pekar in i statisk lagring; anroparen bör inte ändra dess värde. Värdet är tillgängligt för Python-kod som sys.executable.

Denna funktion bör inte anropas före Py_Initialize(), annars returnerar den NULL.

Ändrad i version 3.10: Den returnerar nu NULL om den anropas före Py_Initialize().

Deprecated since version 3.13, will be removed in version 3.15: Använd PyConfig_Get("executable") (sys.executable) istället.

wchar_t *Py_GetPath()
En del av Stabil ABI.

Returnerar standardmodulsökvägen; denna beräknas från programnamnet (anges av PyConfig.program_name) och vissa miljövariabler. Den returnerade strängen består av en serie katalognamn åtskilda av ett plattformsberoende avgränsningstecken. Avgränsningstecknet är ':' på Unix och macOS, ';' på Windows. Den returnerade strängen pekar in i statisk lagring; anroparen bör inte ändra dess värde. Listan sys.path initialiseras med detta värde när tolken startas; den kan (och brukar) modifieras senare för att ändra sökvägen för laddning av moduler.

Denna funktion bör inte anropas före Py_Initialize(), annars returnerar den NULL.

Ändrad i version 3.10: Den returnerar nu NULL om den anropas före Py_Initialize().

Deprecated since version 3.13, will be removed in version 3.15: Använd PyConfig_Get("module_search_paths") (sys.path) istället.

const char *Py_GetVersion()
En del av Stabil ABI.

Returnerar versionen av denna Python-tolk. Detta är en sträng som ser ut ungefär som

"3.0a5+ (py3k:63103M, 12 maj 2008, 00:53:55) \n[GCC 4.2.3]"

Det första ordet (upp till det första mellanslagstecknet) är den aktuella Python-versionen; de första tecknen är major- och minor-versionen åtskilda av en punkt. Den returnerade strängen pekar in i statisk lagring; anroparen bör inte ändra dess värde. Värdet är tillgängligt för Python-kod som sys.version.

Se även konstanten Py_Version.

const char *Py_GetPlatform()
En del av Stabil ABI.

Returnerar plattformsidentifieraren för den aktuella plattformen. På Unix bildas detta av operativsystemets ”officiella” namn, konverterat till gemener, följt av det större revisionsnumret; t.ex. för Solaris 2.x, som också är känt som SunOS 5.x, är värdet 'sunos5'. På macOS är det 'darwin'. På Windows är det 'win'. Den returnerade strängen pekar in i statisk lagring; anroparen ska inte ändra dess värde. Värdet är tillgängligt för Python-kod som sys.platform.

const char *Py_GetCopyright()
En del av Stabil ABI.

Returnera den officiella copyright-strängen för den aktuella Python-versionen, till exempel

'Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam'

Den returnerade strängen pekar in i statisk lagring; anroparen ska inte ändra dess värde. Värdet är tillgängligt för Python-kod som sys.copyright.

const char *Py_GetCompiler()
En del av Stabil ABI.

Returnera en indikation på kompilatorn som användes för att bygga den aktuella Python-versionen, inom hakparenteser, till exempel:

"[GCC 2.7.2.2]"

Den returnerade strängen pekar in i statisk lagring; anroparen ska inte ändra dess värde. Värdet är tillgängligt för Python-kod som en del av variabeln sys.version.

const char *Py_GetBuildInfo()
En del av Stabil ABI.

Returnera information om sekvensnummer och byggdatum och -tid för den aktuella Python-tolkinstansen, till exempel

"#67, 1 Aug 1997, 22:34:28"

Den returnerade strängen pekar in i statisk lagring; anroparen ska inte ändra dess värde. Värdet är tillgängligt för Python-kod som en del av variabeln sys.version.

void PySys_SetArgvEx(int argc, wchar_t **argv, int updatepath)
En del av Stabil ABI.

Detta API behålls för bakåtkompatibilitet: inställningarna PyConfig.argv, PyConfig.parse_argv och PyConfig.safe_path bör användas istället, se Python Initialization Configuration.

Ställ in sys.argv baserat på argc och argv. Dessa parametrar liknar de som skickas till programmets funktion main() med skillnaden att den första posten ska referera till skriptfilen som ska köras istället för den körbara filen som är värd för Python-tolken. Om det inte finns något skript som ska köras kan den första posten i argv vara en tom sträng. Om denna funktion misslyckas med att initiera sys.argv, signaleras ett fatalt tillstånd med Py_FatalError().

Om updatepath är noll är detta allt som funktionen gör. Om updatepath inte är noll, ändrar funktionen även sys.path enligt följande algoritm:

  • Om namnet på ett befintligt skript anges i argv[0], läggs den absoluta sökvägen till den katalog där skriptet finns till sys.path.

  • I annat fall (dvs. om argc är 0 eller argv[0] inte pekar på ett befintligt filnamn) läggs en tom sträng till i sys.path, vilket är samma sak som att lägga till den aktuella arbetskatalogen (".").

Använd Py_DecodeLocale() för att avkoda en bytes-sträng för att få en wchar_t*-sträng.

Se även PyConfig.orig_argv och PyConfig.argv i Python Initialization Configuration.

Anteckning

Det rekommenderas att program som bäddar in Python-tolken för andra ändamål än att exekvera ett enda skript skickar 0 som updatepath, och uppdaterar sys.path själva om så önskas. Se CVE 2008-5983.

På versioner före 3.1.3 kan du uppnå samma effekt genom att manuellt poppa det första sys.path-elementet efter att ha anropat PySys_SetArgv(), till exempel med:

PyRun_SimpleString("import sys; sys.path.pop(0)\n");

Tillagd i version 3.1.3.

Deprecated since version 3.11, will be removed in version 3.15.

void PySys_SetArgv(int argc, wchar_t **argv)
En del av Stabil ABI.

Detta API behålls för bakåtkompatibilitet: inställningarna PyConfig.argv och PyConfig.parse_argv bör användas istället, se Python Initialization Configuration.

Den här funktionen fungerar som PySys_SetArgvEx() med updatepath satt till 1 om inte tolken python startades med -I.

Använd Py_DecodeLocale() för att avkoda en bytes-sträng för att få en wchar_t*-sträng.

Se även PyConfig.orig_argv och PyConfig.argv i Python Initialization Configuration.

Ändrad i version 3.4: Värdet updatepath beror på -I.

Deprecated since version 3.11, will be removed in version 3.15.

void Py_SetPythonHome(const wchar_t *home)
En del av Stabil ABI.

Detta API behålls för bakåtkompatibilitet: inställningen PyConfig.home bör användas istället, se Python Initialization Configuration.

Ställ in standardkatalogen ”home”, det vill säga platsen för Pythons standardbibliotek. Se PYTHONHOME för innebörden av argumentsträngen.

Argumentet ska peka på en nollavslutad teckensträng i statisk lagring vars innehåll inte kommer att ändras under programmets exekvering. Ingen kod i Python-tolken kommer att ändra innehållet i detta lager.

Använd Py_DecodeLocale() för att avkoda en bytes-sträng för att få en wchar_t*-sträng.

Deprecated since version 3.11, will be removed in version 3.15.

wchar_t *Py_GetPythonHome()
En del av Stabil ABI.

Returnerar standard ”home”, det vill säga det värde som anges av PyConfig.home, eller värdet på miljövariabeln PYTHONHOME om den är angiven.

Denna funktion bör inte anropas före Py_Initialize(), annars returnerar den NULL.

Ändrad i version 3.10: Den returnerar nu NULL om den anropas före Py_Initialize().

Deprecated since version 3.13, will be removed in version 3.15: Använd PyConfig_Get("home") eller miljövariabeln PYTHONHOME istället.

Thread State och det globala tolkningslåset

Om inte på en free-threaded-byggnad av CPython, är Python-tolken inte helt trådsäker. För att stödja flertrådade Python-program finns det ett globalt lås, kallat global interpreter lock eller GIL, som måste hållas av den aktuella tråden innan den kan komma åt Python-objekt på ett säkert sätt. Utan låset kan även de enklaste operationer orsaka problem i ett flertrådigt program: till exempel, när två trådar samtidigt ökar referensantalet för samma objekt, kan det sluta med att referensantalet bara ökas en gång istället för två gånger.

Därför finns regeln att endast den tråd som har förvärvat GIL kan operera på Python-objekt eller anropa Python/C API-funktioner. För att emulera samtidig exekvering försöker tolken regelbundet att byta tråd (se sys.setswitchinterval()). Låset släpps också runt potentiellt blockerande I/O-operationer som att läsa eller skriva en fil, så att andra Python-trådar kan köras under tiden.

Python-tolken håller viss trådspecifik bokföringsinformation i en datastruktur som heter PyThreadState, känd som en thread state. Varje OS-tråd har en trådlokal pekare till en PyThreadState; ett trådtillstånd som refereras av denna pekare anses vara attached.

En tråd kan bara ha en attached thread state åt gången. Ett bifogat trådtillstånd är typiskt analogt med att hålla GIL, förutom på free-threaded builds. På byggen med GIL aktiverat, kommer attaching ett trådtillstånd att blockera tills GIL kan förvärvas. Men även på byggen med GIL inaktiverat krävs det fortfarande att man har ett anslutet trådtillstånd för att anropa det mesta av C API.

I allmänhet kommer det alltid att finnas en attached thread state när man använder Pythons C API. Endast i vissa specifika fall (t.ex. i ett Py_BEGIN_ALLOW_THREADS-block) kommer tråden inte att ha ett attached thread state. Om du är osäker, kontrollera om PyThreadState_GetUnchecked() returnerar NULL.

Avlägsna trådtillståndet från tilläggskoden

Den mesta tilläggskoden som manipulerar thread state har följande enkla struktur:

Spara trådtillståndet i en lokal variabel.
... Utför någon blockerande I/O-operation ...
Återställ trådtillståndet från den lokala variabeln.

Detta är så vanligt att det finns ett par makron för att förenkla det:

Py_BEGIN_ALLOW_THREADS
... Gör någon blockerande I/O-operation ...
Py_END_ALLOW_THREADS

Makrot Py_BEGIN_ALLOW_THREADS öppnar ett nytt block och deklarerar en dold lokal variabel; makrot Py_END_ALLOW_THREADS stänger blocket.

Blocket ovan expanderar till följande kod:

PyThreadState *_save;

_save = PyEval_SaveThread();
... Gör någon blockerande I/O-operation ...
PyEval_RestoreThread(_save);

Så här fungerar dessa funktioner:

Den attached thread state håller GIL för hela tolken. När man tar bort attached thread state släpps GIL, vilket gör det möjligt för andra trådar att koppla ett thread state till sin egen tråd, som därmed får GIL och kan börja exekvera. Pekaren till den tidigare attached thread state lagras som en lokal variabel. När man når Py_END_ALLOW_THREADS, skickas trådtillståndet som tidigare var attached till PyEval_RestoreThread(). Denna funktion kommer att blockera tills en annan släpper sin thread state, vilket gör att den gamla thread state kan återanslutas och C API kan anropas igen.

För free-threaded-kompileringar är GIL normalt inte aktuellt, men det är fortfarande nödvändigt att koppla bort thread state för att blockera I/O och långa operationer. Skillnaden är att trådar inte behöver vänta på att GIL frigörs för att koppla sin trådstatus, vilket möjliggör äkta parallellitet med flera kärnor.

Anteckning

Anrop av systemets I/O-funktioner är det vanligaste användningsområdet för att koppla bort thread state, men det kan också vara användbart innan man anropar långvariga beräkningar som inte behöver tillgång till Python-objekt, till exempel komprimerings- eller kryptografiska funktioner som arbetar över minnesbuffertar. Standardmodulerna zlib och hashlib avaktiverar till exempel thread state när de komprimerar eller hashar data.

Icke-Python skapade trådar

När trådar skapas med hjälp av Pythons särskilda API:er (t.ex. modulen threading) associeras de automatiskt med ett trådtillstånd och koden ovan är därför korrekt. Men när trådar skapas från C (t.ex. av ett tredjepartsbibliotek med egen trådhantering) har de inte GIL, eftersom de inte har någon attached thread state.

Om du behöver anropa Python-kod från dessa trådar (ofta kommer detta att vara en del av ett callback-API som tillhandahålls av det tidigare nämnda tredjepartsbiblioteket), måste du först registrera dessa trådar med tolken genom att skapa en attached thread state innan du kan börja använda Python/C API. När du är klar bör du ta bort thread state och slutligen frigöra det.

Funktionerna PyGILState_Ensure() och PyGILState_Release() gör allt detta automatiskt. Det typiska idiomet för att anropa till Python från en C-tråd är:

PyGILState_STATE gstate;
gstate = PyGILState_Ensure();

/* Utför Python-åtgärder här. */
resultat = CallSomeFunction();
/* utvärdera resultat eller hantera undantag */

/* Släpp tråden. Inget Python API tillåts bortom denna punkt. */
PyGILState_Release(gstate);

Observera att funktionerna PyGILState_* förutsätter att det bara finns en global tolk (som skapas automatiskt av Py_Initialize()). Python stöder skapandet av ytterligare tolkar (med Py_NewInterpreter()), men att blanda flera tolkar och API:et PyGILState_* stöds inte. Detta beror på att PyGILState_Ensure() och liknande funktioner som standard attaching ett thread state för huvudtolken, vilket innebär att tråden inte säkert kan interagera med den anropande undertolken.

Stöd för undertolkar i icke-Python-trådar

Om du vill stödja undertolkar med trådar som inte skapats av Python måste du använda API:et PyThreadState_* istället för det traditionella API:et PyGILState_*.

I synnerhet måste du lagra tolktillståndet från den anropande funktionen och skicka det till PyThreadState_New(), som kommer att säkerställa att thread state riktar sig till rätt tolk:

/* Returvärdet av PyInterpreterState_Get() från funktionen som
   funktion som skapade den här tråden. */
PyInterpreterState *interp = ThreadData->interp;
PyThreadState *tstate = PyThreadState_New(interp);
PyThreadState_Swap(tstate);

/* Undertolkarens GIL hålls nu.
   Utför Python-åtgärder här. */
resultat = CallSomeFunction();
/* utvärdera resultat eller hantera undantag */

/* Förstör trådtillståndet. Inget Python API tillåts bortom denna punkt. */
PyThreadState_Clear(tstate);
PyThreadState_DeleteCurrent();

Försiktighetsåtgärder för fork()

En annan viktig sak att notera om trådar är deras beteende inför C fork()-anropet. På de flesta system med fork() kommer det efter att en process har gafflats bara att finnas den tråd som utfärdade gafflingen. Detta har en konkret inverkan både på hur lås måste hanteras och på allt lagrat tillstånd i CPythons körtid.

Det faktum att endast den ”aktuella” tråden finns kvar innebär att eventuella lås som innehas av andra trådar aldrig kommer att släppas. Python löser detta för os.fork() genom att förvärva de lås som den använder internt före förgreningen och släppa dem efteråt. Dessutom återställs alla Lås objekt i barnet. När Python utökas eller bäddas in finns det inget sätt att informera Python om ytterligare (icke-Python) lås som behöver förvärvas före eller återställas efter en fork. OS-faciliteter som pthread_atfork() skulle behöva användas för att åstadkomma samma sak. Dessutom, när Python utökas eller bäddas in, kan anrop av fork() direkt istället för genom os.fork() (och återgå till eller anropa Python) resultera i ett dödläge genom att ett av Pythons interna lås hålls av en tråd som inte längre finns efter förgreningen. PyOS_AfterFork_Child() försöker återställa de nödvändiga låsen, men kan inte alltid göra det.

Det faktum att alla andra trådar försvinner innebär också att CPythons runtime state där måste rensas upp ordentligt, vilket os.fork() gör. Detta innebär att alla andra PyThreadState-objekt som tillhör den aktuella tolken och alla andra PyInterpreterState-objekt måste slutföras. På grund av detta och den speciella karaktären hos ”main”-tolken, bör fork() endast anropas i den tolkens ”main”-tråd, där CPythons globala runtime ursprungligen initialiserades. Det enda undantaget är om exec() kommer att anropas omedelbart efter.

Försiktighetsåtgärder avseende runtime-finalisering

I det sena skedet av interpreter shutdown, efter att ha försökt vänta på att icke-daemon-trådar ska avslutas (även om detta kan avbrytas av KeyboardInterrupt) och efter att ha kört atexit-funktionerna, markeras körtiden som finalizing: Py_IsFinalizing() och sys.is_finalizing() returnerar true. Vid denna tidpunkt är det bara den finaliseringstråd som initierade finaliseringen (vanligtvis huvudtråden) som får förvärva GIL.

Om någon tråd, annan än den avslutande tråden, försöker lägga till en thread state under avslutningen, antingen explicit eller implicit, går tråden in i ett permanent blockerat tillstånd där den förblir tills programmet avslutas. I de flesta fall är detta ofarligt, men det kan leda till dödläge om ett senare steg i slutförandet försöker förvärva ett lås som ägs av den blockerade tråden, eller på annat sätt väntar på den blockerade tråden.

Brutto? Ja, det är det. Detta förhindrar slumpmässiga krascher och / eller oväntat hoppade över C ++ -avslutningar längre upp i samtalsstacken när sådana trådar tvångsavslutades här i CPython 3.13 och tidigare. CPythons körtid thread state C API:er har aldrig haft några förväntningar på felrapportering eller hantering vid thread state attachment-tid som skulle ha möjliggjort en graciös utgång från denna situation. Att ändra det skulle kräva nya stabila C API: er och skriva om majoriteten av C-koden i CPython-ekosystemet för att använda dem med felhantering.

API på hög nivå

Dessa är de vanligaste typerna och funktionerna när du skriver C-tilläggskod eller när du bäddar in Python-tolken:

type PyInterpreterState
En del av Begränsat API (som en ogenomskinlig struktur).

Denna datastruktur representerar det tillstånd som delas av ett antal samarbetande trådar. Trådar som tillhör samma tolk delar sin moduladministration och några andra interna objekt. Det finns inga offentliga medlemmar i denna struktur.

Trådar som tillhör olika tolkar delar till en början ingenting, förutom processstatus som tillgängligt minne, öppna filbeskrivare och liknande. Det globala tolklåset delas också av alla trådar, oavsett vilken tolk de tillhör.

type PyThreadState
En del av Begränsat API (som en ogenomskinlig struktur).

Denna datastruktur representerar tillståndet för en enskild tråd. Den enda offentliga datamedlemmen är:

PyInterpreterState *interp

Den här trådens tolkstatus.

void PyEval_InitThreads()
En del av Stabil ABI.

Föråldrad funktion som inte gör någonting.

I Python 3.6 och äldre skapade den här funktionen GIL om den inte fanns.

Ändrad i version 3.9: Funktionen gör nu ingenting.

Ändrad i version 3.7: Den här funktionen anropas nu av Py_Initialize(), så du behöver inte anropa den själv längre.

Ändrad i version 3.2: Den här funktionen kan inte längre anropas före Py_Initialize().

Föråldrad sedan version 3.9.

PyThreadState *PyEval_SaveThread()
En del av Stabil ABI.

Avlägsna attached thread state och returnera det. Tråden kommer inte att ha någon thread state när den återlämnas.

void PyEval_RestoreThread(PyThreadState *tstate)
En del av Stabil ABI.

Sätt attached thread state till tstate. Det passerade thread state bör inte vara attached, annars uppstår deadlock. tstate kommer att vara attached vid returnering.

Anteckning

Om du anropar den här funktionen från en tråd när körtiden håller på att slutföras kommer tråden att hänga kvar tills programmet avslutas, även om tråden inte skapades av Python. Se Försiktighetsåtgärder avseende runtime-finalisering för mer information.

Ändrad i version 3.14: Hänger den aktuella tråden i stället för att avsluta den, om den anropas medan tolken håller på att slutföras.

PyThreadState *PyThreadState_Get()
En del av Stabil ABI.

Returnerar attached thread state. Om tråden inte har något anslutet trådtillstånd (t.ex. inuti ett Py_BEGIN_ALLOW_THREADS block), så ger detta ett fatalt fel (så att anroparen inte behöver kontrollera för NULL).

Se även PyThreadState_GetUnchecked().

PyThreadState *PyThreadState_GetUnchecked()

Liknar PyThreadState_Get(), men dödar inte processen med ett fatalt fel om det är NULL. Den som anropar är ansvarig för att kontrollera om resultatet är NULL.

Tillagd i version 3.13: I Python 3.5 till 3.12 var funktionen privat och känd som _PyThreadState_UncheckedGet().

PyThreadState *PyThreadState_Swap(PyThreadState *tstate)
En del av Stabil ABI.

Sätter attached thread state till tstate, och returnerar thread state som var attached innan anropet.

Denna funktion är säker att anropa utan en attached thread state; den kommer helt enkelt att returnera NULL vilket indikerar att det inte fanns någon tidigare thread state.

Anteckning

I likhet med PyGILState_Ensure(), kommer denna funktion att hänga upp tråden om runtime håller på att slutföras.

Följande funktioner använder trådlokal lagring och är inte kompatibla med undertolkare:

PyGILState_STATE PyGILState_Ensure()
En del av Stabil ABI.

Säkerställer att den aktuella tråden är redo att anropa Python C API oavsett Pythons aktuella status eller attached thread state. Detta kan anropas hur många gånger som helst av en tråd så länge som varje anrop matchas med ett anrop till PyGILState_Release(). I allmänhet kan andra trådrelaterade API:er användas mellan anropen av PyGILState_Ensure() och PyGILState_Release() så länge som trådens tillstånd återställs till dess tidigare tillstånd före Release(). Till exempel är normal användning av makrona Py_BEGIN_ALLOW_THREADS och Py_END_ALLOW_THREADS acceptabel.

Returvärdet är ett opakt ”handtag” till attached thread state när PyGILState_Ensure() anropades, och måste skickas till PyGILState_Release() för att säkerställa att Python lämnas i samma tillstånd. Även om rekursiva anrop är tillåtna, kan dessa handtag inte delas - varje unikt anrop till PyGILState_Ensure() måste spara handtaget för sitt anrop till PyGILState_Release().

När funktionen returneras kommer det att finnas en attached thread state och tråden kommer att kunna anropa godtycklig Python-kod. Misslyckande är ett fatalt fel.

Varning

Det är osäkert att anropa denna funktion när runtime håller på att avslutas. Om du gör det kommer du antingen att hänga upp tråden tills programmet avslutas, eller i sällsynta fall krascha tolken helt och hållet. Se Försiktighetsåtgärder avseende runtime-finalisering för mer information.

Ändrad i version 3.14: Hänger den aktuella tråden i stället för att avsluta den, om den anropas medan tolken håller på att slutföras.

void PyGILState_Release(PyGILState_STATE)
En del av Stabil ABI.

Frigör alla resurser som tidigare förvärvats. Efter detta anrop kommer Pythons tillstånd att vara detsamma som det var före motsvarande PyGILState_Ensure()-anrop (men i allmänhet kommer detta tillstånd att vara okänt för anroparen, därav användningen av GILState API).

Varje anrop till PyGILState_Ensure() måste motsvaras av ett anrop till PyGILState_Release() på samma tråd.

PyThreadState *PyGILState_GetThisThreadState()
En del av Stabil ABI.

Hämta attached thread state för den här tråden. Kan returnera NULL om inget GILState API har använts på den aktuella tråden. Observera att huvudtråden alltid har ett sådant trådtillstånd, även om inget anrop om automatiskt trådtillstånd har gjorts på huvudtråden. Detta är huvudsakligen en hjälp/diagnostisk funktion.

Anteckning

Den här funktionen tar inte hänsyn till thread states som skapats av något annat än PyGILState_Ensure() (t.ex. PyThreadState_New()). Föredrar PyThreadState_Get() eller PyThreadState_GetUnchecked() för de flesta fall.

int PyGILState_Check()

Returnerar 1 om den aktuella tråden håller i GIL och 0 annars. Denna funktion kan anropas från vilken tråd som helst när som helst. Endast om den har fått sin thread state initialiserad via PyGILState_Ensure() kommer den att returnera 1. Detta är huvudsakligen en hjälp/diagnostisk funktion. Den kan vara användbar till exempel i återuppringningssammanhang eller minnesallokeringsfunktioner när vetskapen om att GIL är låst kan göra det möjligt för anroparen att utföra känsliga åtgärder eller på annat sätt bete sig annorlunda.

Anteckning

Om den aktuella Python-processen någonsin har skapat en undertolk, kommer denna funktion alltid att returnera 1. Föredrar PyThreadState_GetUnchecked() för de flesta fall.

Tillagd i version 3.4.

Följande makron används normalt utan efterföljande semikolon; se exempel på hur de används i Pythons källdistribution.

Py_BEGIN_ALLOW_THREADS
En del av Stabil ABI.

Detta makro expanderar till { PyThreadState *_save; _save = PyEval_SaveThread();. Observera att det innehåller en inledande parentes; det måste matchas med ett följande Py_END_ALLOW_THREADS-makro. Se ovan för vidare diskussion om detta makro.

Py_END_ALLOW_THREADS
En del av Stabil ABI.

Detta makro expanderar till PyEval_RestoreThread(_save); }. Observera att det innehåller en avslutande parentes; det måste matchas med ett tidigare Py_BEGIN_ALLOW_THREADS-makro. Se ovan för ytterligare diskussion om detta makro.

Py_BLOCK_THREADS
En del av Stabil ABI.

Detta makro expanderar till PyEval_RestoreThread(_save);: det är likvärdigt med Py_END_ALLOW_THREADS utan den avslutande parentesen.

Py_UNBLOCK_THREADS
En del av Stabil ABI.

Detta makro expanderar till _save = PyEval_SaveThread();: det motsvarar Py_BEGIN_ALLOW_THREADS utan inledande hängslen och variabeldeklaration.

API på låg nivå

Alla följande funktioner måste anropas efter Py_Initialize().

Ändrad i version 3.7: Py_Initialize() initierar nu GIL och sätter en attached thread state.

PyInterpreterState *PyInterpreterState_New()
En del av Stabil ABI.

Skapar ett nytt tolktillståndsobjekt. En attached thread state behövs inte, men kan eventuellt existera om det är nödvändigt att serialisera anrop till denna funktion.

Utlöser en auditing event cpython.PyInterpreterState_New utan argument.

void PyInterpreterState_Clear(PyInterpreterState *interp)
En del av Stabil ABI.

Återställer all information i ett tolkstatusobjekt. Det måste finnas en attached thread state för tolken.

Utlöser en auditing event cpython.PyInterpreterState_Clear utan argument.

void PyInterpreterState_Delete(PyInterpreterState *interp)
En del av Stabil ABI.

Förstör ett tolktillståndsobjekt. Det bör inte finnas något attached thread state för måltolken. Tolkens tillstånd måste ha återställts med ett tidigare anrop till PyInterpreterState_Clear().

PyThreadState *PyThreadState_New(PyInterpreterState *interp)
En del av Stabil ABI.

Skapar ett nytt trådtillståndsobjekt som hör till det givna tolkobjektet. En attached thread state behövs inte.

void PyThreadState_Clear(PyThreadState *tstate)
En del av Stabil ABI.

Återställer all information i ett thread state-objekt. tstate måste vara attached

Ändrad i version 3.9: Denna funktion anropar nu PyThreadState.on_delete callback. Tidigare skedde det i PyThreadState_Delete().

Ändrad i version 3.13: Återkallelsen PyThreadState.on_delete togs bort.

void PyThreadState_Delete(PyThreadState *tstate)
En del av Stabil ABI.

Förstör ett thread state-objekt. tstate bör inte vara attached till någon tråd. tstate måste ha återställts med ett tidigare anrop till PyThreadState_Clear().

void PyThreadState_DeleteCurrent(void)

Avlägsna attached thread state (som måste ha återställts med ett tidigare anrop till PyThreadState_Clear()) och förstör det sedan.

Ingen thread state kommer att vara attached vid returnering.

PyFrameObject *PyThreadState_GetFrame(PyThreadState *tstate)
En del av Stabil ABI sedan version 3.10.

Hämta den aktuella bilden av Python-trådtillståndet tstate.

Returnerar en strong reference. Returnerar NULL om ingen ram körs för närvarande.

Se även PyEval_GetFrame().

tstate får inte vara NULL, och måste vara attached.

Tillagd i version 3.9.

uint64_t PyThreadState_GetID(PyThreadState *tstate)
En del av Stabil ABI sedan version 3.10.

Hämta den unika thread state-identifieraren för Python-trådtillståndet tstate.

tstate får inte vara NULL, och måste vara attached.

Tillagd i version 3.9.

PyInterpreterState *PyThreadState_GetInterpreter(PyThreadState *tstate)
En del av Stabil ABI sedan version 3.10.

Hämta tolken för Python-trådtillståndet tstate.

tstate får inte vara NULL, och måste vara attached.

Tillagd i version 3.9.

void PyThreadState_EnterTracing(PyThreadState *tstate)

Avbryt spårning och profilering i Python-trådtillståndet tstate.

Återuppta dem med hjälp av funktionen PyThreadState_LeaveTracing().

Tillagd i version 3.11.

void PyThreadState_LeaveTracing(PyThreadState *tstate)

Återuppta spårning och profilering i Python-trådtillståndet tstate som avbröts av funktionen PyThreadState_EnterTracing().

Se även funktionerna PyEval_SetTrace() och PyEval_SetProfile().

Tillagd i version 3.11.

PyInterpreterState *PyInterpreterState_Get(void)
En del av Stabil ABI sedan version 3.9.

Hämta den aktuella tolken.

Utfärdar ett allvarligt fel om det inte finns någon attached thread state. Den kan inte returnera NULL.

Tillagd i version 3.9.

int64_t PyInterpreterState_GetID(PyInterpreterState *interp)
En del av Stabil ABI sedan version 3.7.

Returnerar tolkens unika ID. Om något fel inträffade returneras -1 och ett fel anges.

Den som anropar måste ha en attached thread state.

Tillagd i version 3.7.

PyObject *PyInterpreterState_GetDict(PyInterpreterState *interp)
En del av Stabil ABI sedan version 3.8.

Returnerar en ordbok i vilken tolkspecifika data kan lagras. Om denna funktion returnerar NULL har inget undantag uppstått och den som anropar bör anta att ingen tolkspecifik dict finns tillgänglig.

Detta är inte en ersättning för PyModule_GetState(), som tillägg bör använda för att lagra tolkspecifik tillståndsinformation.

Tillagd i version 3.8.

typedef PyObject *(*_PyFrameEvalFunction)(PyThreadState *tstate, _PyInterpreterFrame *frame, int throwflag)

Typ av utvärderingsfunktion för en ram.

Parametern throwflag används av generatorns metod throw(): om den är icke-noll, hanteras det aktuella undantaget.

Ändrad i version 3.9: Funktionen tar nu en tstate parameter.

Ändrad i version 3.11: Parametern frame ändrades från PyFrameObject* till _PyInterpreterFrame*.

_PyFrameEvalFunction _PyInterpreterState_GetEvalFrameFunc(PyInterpreterState *interp)

Hämta funktionen för utvärdering av ramen.

Se PEP 523 ”Lägga till ett API för ramutvärdering till CPython”.

Tillagd i version 3.9.

void _PyInterpreterState_SetEvalFrameFunc(PyInterpreterState *interp, _PyFrameEvalFunction eval_frame)

Ställ in funktionen för utvärdering av ramen.

Se PEP 523 ”Lägga till ett API för ramutvärdering till CPython”.

Tillagd i version 3.9.

PyObject *PyThreadState_GetDict()
Returnera värde: Lånad referens. En del av Stabil ABI.

Returnerar en ordbok där tillägg kan lagra trådspecifik tillståndsinformation. Varje tillägg bör använda en unik nyckel som används för att lagra tillstånd i ordlistan. Det är okej att anropa denna funktion när ingen thread state är attached. Om denna funktion returnerar NULL har inget undantag uppstått och den som anropar bör anta att inget trådtillstånd är kopplat.

int PyThreadState_SetAsyncExc(unsigned long id, PyObject *exc)
En del av Stabil ABI.

Asynkronisera ett undantag i en tråd. Argumentet id är tråd-id för måltråden; exc är undantagsobjektet som ska utlösas. Denna funktion stjäl inte några referenser till exc. För att förhindra naivt missbruk måste du skriva ditt eget C-tillägg för att anropa detta. Måste anropas med en attached thread state. Returnerar antalet modifierade trådtillstånd; detta är normalt ett, men kommer att vara noll om tråd-id inte hittas. Om exc är NULL, rensas det väntande undantaget (om det finns något) för tråden. Detta ger inte upphov till några undantag.

Ändrad i version 3.7: Typen av parametern id ändrades från long till unsigned long.

void PyEval_AcquireThread(PyThreadState *tstate)
En del av Stabil ABI.

Attach tstate till den aktuella tråden, som inte får vara NULL eller redan attached.

Den anropande tråden får inte redan ha ett attached thread state.

Anteckning

Om du anropar den här funktionen från en tråd när körtiden håller på att slutföras kommer tråden att hänga kvar tills programmet avslutas, även om tråden inte skapades av Python. Se Försiktighetsåtgärder avseende runtime-finalisering för mer information.

Ändrad i version 3.8: Uppdaterad för att överensstämma med PyEval_RestoreThread(), Py_END_ALLOW_THREADS(), och PyGILState_Ensure(), och avsluta den aktuella tråden om den anropas medan tolken håller på att slutföras.

Ändrad i version 3.14: Hänger den aktuella tråden i stället för att avsluta den, om den anropas medan tolken håller på att slutföras.

PyEval_RestoreThread() är en funktion på högre nivå som alltid är tillgänglig (även när trådar inte har initialiserats).

void PyEval_ReleaseThread(PyThreadState *tstate)
En del av Stabil ABI.

Avlägsna attached thread state. Argumentet tstate, som inte får vara NULL, används bara för att kontrollera att det representerar attached thread state — om det inte gör det, rapporteras ett allvarligt fel.

PyEval_SaveThread() är en funktion på högre nivå som alltid är tillgänglig (även när trådar inte har initialiserats).

Stöd för undertolkning

Även om du i de flesta fall bara kommer att bädda in en enda Python-tolk, finns det fall där du behöver skapa flera oberoende tolkar i samma process och kanske till och med i samma tråd. Undertolkare gör det möjligt för dig att göra det.

Tolken ”main” är den första som skapas när runtime initialiseras. Det är vanligtvis den enda Python-tolken i en process. Till skillnad från undertolkare har huvudtolkaren unika processglobala ansvarsområden som signalhantering. Den är också ansvarig för exekvering under initiering av körtiden och är vanligtvis den aktiva tolken under slutförande av körtiden. Funktionen PyInterpreterState_Main() returnerar en pekare till dess tillstånd.

Du kan växla mellan undertolkare med hjälp av funktionen PyThreadState_Swap(). Du kan skapa och förstöra dem med hjälp av följande funktioner:

type PyInterpreterConfig

Struktur som innehåller de flesta parametrar för att konfigurera en sub-tolk. Dess värden används endast i Py_NewInterpreterFromConfig() och ändras aldrig av körtiden.

Tillagd i version 3.12.

Strukturfält:

int use_main_obmalloc

Om detta är 0 kommer undertolken att använda sitt eget ”objekt”-allokeringstillstånd. Annars kommer den att använda (dela) huvudtolkens.

Om detta är 0 så måste check_multi_interp_extensions vara 1 (icke-noll). Om detta är 1 så får inte gil vara PyInterpreterConfig_OWN_GIL.

int allow_fork

Om detta är 0 kommer körtiden inte att stödja forking av processen i någon tråd där undertolken för närvarande är aktiv. Annars är fork obegränsad.

Observera att modulen subprocess fortfarande fungerar när fork inte är tillåtet.

int allow_exec

Om detta är 0 kommer körtiden inte att stödja ersättning av den aktuella processen via exec (t.ex. os.execv()) i någon tråd där undertolken för närvarande är aktiv. Annars är exec obegränsat.

Observera att modulen subprocess fortfarande fungerar när exec inte är tillåtet.

int allow_threads

Om detta är 0 så kommer undertolkarens modul threading inte att skapa trådar. Annars är trådar tillåtna.

int allow_daemon_threads

Om detta är 0 så kommer inte undertolkarens modul threading att skapa daemon-trådar. Annars är daemon-trådar tillåtna (så länge som allow_threads är icke-noll).

int check_multi_interp_extensions

Om detta är 0 så kan alla tilläggsmoduler importeras, inklusive äldre moduler (enfasig init), i alla trådar där undertolkaren för närvarande är aktiv. Annars får endast tilläggsmoduler för flerfasig init (se PEP 489) importeras. (Se även Py_mod_multiple_interpreters.)

Detta måste vara 1 (icke-noll) om use_main_obmalloc är 0.

int gil

Detta bestämmer hur GIL ska fungera för undertolken. Det kan vara något av följande:

PyInterpreterConfig_DEFAULT_GIL

Använd standardvalet (PyInterpreterConfig_SHARED_GIL).

PyInterpreterConfig_SHARED_GIL

Använd (dela) huvudtolkens GIL.

PyInterpreterConfig_OWN_GIL

Använd undertolkarens egen GIL.

Om detta är PyInterpreterConfig_OWN_GIL så måste PyInterpreterConfig.use_main_obmalloc vara 0.

PyStatus Py_NewInterpreterFromConfig(PyThreadState **tstate_p, const PyInterpreterConfig *config)

Skapa en ny subinterpreter. Detta är en (nästan) helt separat miljö för exekvering av Python-kod. I synnerhet har den nya tolken separata, oberoende versioner av alla importerade moduler, inklusive de grundläggande modulerna builtins, __main__ och sys. Tabellen över inlästa moduler (sys.modules) och sökvägen för moduler (sys.path) är också separata. Den nya miljön har ingen variabel sys.argv. Den har nya standard I/O-strömfilobjekt sys.stdin, sys.stdout och sys.stderr (dessa hänvisar dock till samma underliggande filbeskrivare).

Den angivna config styr de alternativ som tolken initieras med.

Vid framgång kommer tstate_p att sättas till det första thread state som skapats i den nya sub-interpretern. Detta trådtillstånd är attached. Observera att ingen egentlig tråd skapas; se diskussionen om trådtillstånd nedan. Om skapandet av den nya tolken misslyckas, sätts tstate_p till NULL; inget undantag sätts eftersom undantagstillståndet lagras i attached thread state, som kanske inte existerar.

Liksom alla andra Python/C API-funktioner måste ett attached thread state finnas innan denna funktion anropas, men det kan vara fristående när funktionen returneras. Vid framgång kommer det returnerade trådtillståndet att vara attached. Om subtolken skapas med sin egen GIL kommer attached thread state för den anropande tolken att lösgöras. När funktionen returneras kommer den nya tolkens thread state att vara attached till den aktuella tråden och den föregående tolkens attached thread state kommer att förbli detached.

Tillagd i version 3.12.

Undertolkar är mest effektiva när de är isolerade från varandra, med vissa funktioner begränsade:

PyInterpreterConfig config = {
    .use_main_obmalloc = 0,
    .allow_fork = 0,
    .allow_exec = 0,
    .allow_threads = 1,
    .allow_daemon_threads = 0,
    .check_multi_interp_extensions = 1,
    .gil = PyInterpreterConfig_OWN_GIL,
};
PyThreadState *tstate = NULL;
PyStatus status = Py_NewInterpreterFromConfig(&tstate, &config);
if (PyStatus_Exception(status)) {
    Py_ExitStatusException(status);
}

Observera att config endast används kortvarigt och inte ändras. Under initialiseringen konverteras configs värden till olika PyInterpreterState-värden. En skrivskyddad kopia av config kan lagras internt på PyInterpreterState.

Tilläggsmoduler delas mellan (under)tolkarna enligt följande:

  • För moduler som använder initialisering i flera faser, t.ex. PyModule_FromDefAndSpec(), skapas och initieras ett separat modulobjekt för varje tolk. Endast statiska och globala variabler på C-nivå delas mellan dessa modulobjekt.

  • För moduler som använder enfasinitialisering, t.ex. PyModule_Create(), initieras ett visst tillägg normalt första gången det importeras, och en (ytlig) kopia av modulens ordbok sparas. När samma tillägg importeras av en annan (under)tolkare initieras en ny modul och fylls med innehållet i denna kopia; tilläggets init-funktion anropas inte. Objekten i modulens ordbok delas därmed mellan (under)tolkarna, vilket kan orsaka oönskat beteende (se Bugs and caveats nedan).

    Observera att detta skiljer sig från vad som händer när ett tillägg importeras efter att tolken har initialiserats helt på nytt genom anrop av Py_FinalizeEx() och Py_Initialize(); i så fall anropas tilläggets funktion initmodule igen. Precis som med initialisering i flera faser innebär detta att endast statiska och globala variabler på C-nivå delas mellan dessa moduler.

PyThreadState *Py_NewInterpreter(void)
En del av Stabil ABI.

Skapa en ny under-tolk. Detta är i huvudsak bara ett omslag runt Py_NewInterpreterFromConfig() med en konfiguration som bevarar det befintliga beteendet. Resultatet är en oisolerad undertolk som delar huvudtolkens GIL, tillåter fork/exec, tillåter daemon-trådar och tillåter enfasiga init-moduler.

void Py_EndInterpreter(PyThreadState *tstate)
En del av Stabil ABI.

Förstör den (under)tolk som representeras av den angivna thread state. Det givna trådtillståndet måste vara attached. När anropet returneras kommer det inte att finnas något attached thread state. Alla trådtillstånd som är associerade med denna tolk förstörs.

Py_FinalizeEx() kommer att förstöra alla undertolkare som inte uttryckligen har förstörts vid den tidpunkten.

A Per tolk GIL

Med Py_NewInterpreterFromConfig() kan du skapa en subtolk som är helt isolerad från andra tolkar, inklusive att ha sin egen GIL. Den viktigaste fördelen med denna isolering är att en sådan tolk kan exekvera Python-kod utan att blockeras av andra tolkar eller blockera några andra. På så sätt kan en enda Python-process verkligen dra nytta av flera processorkärnor när den kör Python-kod. Isoleringen uppmuntrar också till ett annat sätt att hantera samtidighet än att bara använda trådar. (Se PEP 554.)

Att använda en isolerad tolk kräver vaksamhet när det gäller att bevara isoleringen. Det innebär särskilt att inte dela några objekt eller föränderligt tillstånd utan garantier om trådsäkerhet. Även objekt som annars är oföränderliga (t.ex. None, (1, 5)) kan normalt inte delas på grund av refcount. En enkel men mindre effektiv metod för att komma runt detta är att använda ett globalt lås för all användning av ett tillstånd (eller objekt). Alternativt kan effektivt oföränderliga objekt (som heltal eller strängar) göras säkra trots deras refcount genom att göra dem till immortal. Faktum är att detta har gjorts för de inbyggda singletonerna, små heltal och ett antal andra inbyggda objekt.

Om du bevarar isoleringen kommer du att få tillgång till riktiga flerkärniga datorer utan de komplikationer som följer med free-threading. Om du inte bevarar isoleringen kommer du att utsättas för alla konsekvenser av free-threading, inklusive tävlingar och krascher som är svåra att felsöka.

Bortsett från det är en av de största utmaningarna med att använda flera isolerade tolkar hur man kommunicerar mellan dem på ett säkert (inte bryta isoleringen) och effektivt sätt. Runtime och stdlib tillhandahåller ännu inte någon standardmetod för detta. En framtida stdlib-modul skulle hjälpa till att minska ansträngningen att bevara isoleringen och exponera effektiva verktyg för att kommunicera (och dela) data mellan tolkar.

Tillagd i version 3.12.

Buggar och förbehåll

Eftersom undertolkar (och huvudtolken) är en del av samma process är isoleringen mellan dem inte perfekt — till exempel kan de (av misstag eller illvilligt) påverka varandras öppna filer genom att använda filoperationer på låg nivå som os.close(). På grund av det sätt som tillägg delas mellan (under)tolkar kan det hända att vissa tillägg inte fungerar korrekt; detta är särskilt troligt när man använder enfasinitialisering eller (statiska) globala variabler. Det är möjligt att infoga objekt som skapats i en subtolk i ett namnrymd i en annan (sub-)tolk; detta bör undvikas om möjligt.

Särskild försiktighet bör iakttas för att undvika att dela användardefinierade funktioner, metoder, instanser eller klasser mellan undertolkare, eftersom importoperationer som utförs av sådana objekt kan påverka fel (under)tolkares ordlista över inlästa moduler. Det är lika viktigt att undvika att dela objekt från vilka ovanstående kan nås.

Notera också att det är känsligt att kombinera denna funktionalitet med PyGILState_* API:er, eftersom dessa API:er antar en bijektion mellan Python-trådtillstånd och trådar på OS-nivå, ett antagande som bryts av närvaron av undertolkare. Det rekommenderas starkt att du inte byter undertolkare mellan ett par matchande PyGILState_Ensure()- och PyGILState_Release()-anrop. Dessutom kommer tillägg (som ctypes) som använder dessa API:er för att tillåta anrop av Python-kod från trådar som inte skapats av Python förmodligen att brytas när man använder undertolkare.

Asynkrona notifieringar

Det finns en mekanism för att göra asynkrona meddelanden till tolkens huvudtråd. Dessa meddelanden har formen av en funktionspekare och ett void-pekarargument.

int Py_AddPendingCall(int (*func)(void*), void *arg)
En del av Stabil ABI.

Schemalägg en funktion som ska anropas från tolkens huvudtråd. Vid framgång returneras 0 och func köas för att anropas i huvudtråden. Vid misslyckande returneras -1 utan att något undantag anges.

När func har köats framgångsrikt kommer den evventuellt att anropas från tolkens huvudtråd med argumentet arg. Den kommer att anropas asynkront i förhållande till normalt körande Python-kod, men med båda dessa villkor uppfyllda:

func måste returnera 0 vid framgång, eller -1 vid misslyckande med en undantagsuppsättning. func kommer inte att avbrytas för att utföra ett annat asynkront meddelande rekursivt, men det kan fortfarande avbrytas för att byta tråd om thread state är fristående.

Denna funktion behöver inte en attached thread state. Men för att anropa denna funktion i en subinterpreter måste anroparen ha en attached thread state. Annars kan funktionen func schemaläggas så att den anropas från fel tolk.

Varning

Detta är en lågnivåfunktion som endast är användbar i mycket speciella fall. Det finns ingen garanti för att func kommer att anropas så snabbt som möjligt. Om huvudtråden är upptagen med att utföra ett systemanrop kommer func inte att anropas innan systemanropet returneras. Den här funktionen är i allmänhet inte lämplig för anrop av Python-kod från godtyckliga C-trådar. Använd istället PyGILState API.

Tillagd i version 3.1.

Ändrad i version 3.9: Om denna funktion anropas i en subinterpreter är funktionen func nu schemalagd att anropas från subinterpretern, istället för att anropas från huvudinterpretern. Varje undertolk har nu sin egen lista över schemalagda anrop.

Profilering och spårning

Python-tolken ger stöd på låg nivå för att koppla till profilerings- och exekveringsspårningsfunktioner. Dessa används för verktyg för profilering, felsökning och täckningsanalys.

Detta C-gränssnitt gör det möjligt för profilerings- eller spårningskoden att undvika omkostnaderna för anrop via anropsbara objekt på Python-nivå och istället göra ett direkt anrop av C-funktioner. De viktigaste egenskaperna hos funktionen har inte ändrats; gränssnittet gör att spårningsfunktioner kan installeras per tråd och de grundläggande händelser som rapporteras till spårningsfunktionen är desamma som rapporterades till spårningsfunktionerna på Python-nivå i tidigare versioner.

typedef int (*Py_tracefunc)(PyObject *obj, PyFrameObject *frame, int what, PyObject *arg)

Typ av spårningsfunktion som registrerats med PyEval_SetProfile() och PyEval_SetTrace(). Den första parametern är det objekt som skickas till registreringsfunktionen som obj, frame är det frame-objekt som händelsen gäller, what är en av konstanterna PyTrace_CALL, PyTrace_EXCEPTION, PyTrace_LINE, PyTrace_RETURN, PyTrace_C_CALL, PyTrace_C_EXCEPTION, PyTrace_C_RETURN, eller PyTrace_OPCODE, och arg beror på värdet av what:

Värde av vad

Betydelse av arg

PyTrace_CALL

Alltid Py_None.

PyTrace_EXCEPTION

Information om undantag som returneras av sys.exc_info().

PyTrace_LINE

Alltid Py_None.

PyTrace_RETURN

Värde som returneras till den som anropar, eller NULL om det orsakas av ett undantag.

PyTrace_C_CALL

Funktionsobjekt som anropas.

PyTrace_C_EXCEPTION

Funktionsobjekt som anropas.

PyTrace_C_RETURN

Funktionsobjekt som anropas.

PyTrace_OPCODE

Alltid Py_None.
int PyTrace_CALL

Värdet på what-parametern till en Py_tracefunc-funktion när ett nytt anrop till en funktion eller metod rapporteras, eller en ny inmatning i en generator. Observera att skapandet av iteratorn för en generatorfunktion inte rapporteras eftersom det inte sker någon kontrollöverföring till Python-bytekoden i motsvarande ram.

int PyTrace_EXCEPTION

Värdet på what parametern till en Py_tracefunc funktion när ett undantag har uppstått. Återkallningsfunktionen anropas med detta värde för what när efter att någon bytecode har bearbetats varefter undantaget blir inställt inom den ram som exekveras. Effekten av detta är att eftersom undantagsutbredningen gör att Python-stacken rullas upp, anropas callbacken vid återkomst till varje ram när undantaget sprids. Endast spårningsfunktioner tar emot dessa händelser; de behövs inte av profileraren.

int PyTrace_LINE

Det värde som skickas som what-parameter till en Py_tracefunc-funktion (men inte en profileringsfunktion) när en radnummerhändelse rapporteras. Den kan inaktiveras för en bildruta genom att sätta f_trace_lines till 0 för den bildrutan.

int PyTrace_RETURN

Värdet för what-parametern till Py_tracefunc-funktioner när ett anrop är på väg att returneras.

int PyTrace_C_CALL

Värdet för what-parametern till Py_tracefunc-funktioner när en C-funktion ska anropas.

int PyTrace_C_EXCEPTION

Värdet för what-parametern till Py_tracefunc-funktioner när en C-funktion har orsakat ett undantag.

int PyTrace_C_RETURN

Värdet för what-parametern till Py_tracefunc-funktioner när en C-funktion har returnerats.

int PyTrace_OPCODE

Värdet för what-parametern till Py_tracefunc-funktioner (men inte profileringsfunktioner) när en ny opcode ska exekveras. Denna händelse sänds inte ut som standard: den måste uttryckligen begäras genom att ställa in f_trace_opcodes till 1 på ramen.

void PyEval_SetProfile(Py_tracefunc func, PyObject *obj)

Ställ in profileringsfunktionen till func. Parametern obj skickas till funktionen som dess första parameter och kan vara vilket Python-objekt som helst eller NULL. Om profilfunktionen behöver upprätthålla tillstånd är det praktiskt och trådsäkert att använda ett annat värde för obj för varje tråd för att lagra det. Profilfunktionen anropas för alla övervakade händelser utom PyTrace_LINE PyTrace_OPCODE och PyTrace_EXCEPTION.

Se även funktionen sys.setprofile().

Den som anropar måste ha en attached thread state.

void PyEval_SetProfileAllThreads(Py_tracefunc func, PyObject *obj)

Som PyEval_SetProfile() men ställer in profilfunktionen i alla pågående trådar som tillhör den aktuella tolken istället för att bara ställa in den i den aktuella tråden.

Den som anropar måste ha en attached thread state.

Precis som PyEval_SetProfile() ignorerar denna funktion alla undantag som uppstår när profilfunktionerna ställs in i alla trådar.

Tillagd i version 3.12.

void PyEval_SetTrace(Py_tracefunc func, PyObject *obj)

Ställ in spårningsfunktionen till func. Detta liknar PyEval_SetProfile(), förutom att spårningsfunktionen tar emot händelser som rör radnummer och per-opcode, men inte händelser som rör anrop av C-funktionsobjekt. En spårningsfunktion som registreras med PyEval_SetTrace() kommer inte att ta emot PyTrace_C_CALL, PyTrace_C_EXCEPTION eller PyTrace_C_RETURN som värde för parametern what.

Se även funktionen sys.settrace().

Den som anropar måste ha en attached thread state.

void PyEval_SetTraceAllThreads(Py_tracefunc func, PyObject *obj)

Som PyEval_SetTrace() men ställer in spårningsfunktionen i alla pågående trådar som tillhör den aktuella tolken istället för att bara ställa in den i den aktuella tråden.

Den som anropar måste ha en attached thread state.

Precis som PyEval_SetTrace() ignorerar denna funktion alla undantag som uppstår när spårningsfunktionerna ställs in i alla trådar.

Tillagd i version 3.12.

Referensspårning

Tillagd i version 3.13.

typedef int (*PyRefTracer)(PyObject*, int event, void *data)

Typen av spårningsfunktion som registrerats med PyRefTracer_SetTracer(). Den första parametern är ett Python-objekt som just har skapats (när event är satt till PyRefTracer_CREATE) eller håller på att förstöras (när event är satt till PyRefTracer_DESTROY). Argumentet data är den opaka pekare som tillhandahölls när PyRefTracer_SetTracer() anropades.

Tillagd i version 3.13.

int PyRefTracer_CREATE

Värdet för parametern event till PyRefTracer-funktioner när ett Python-objekt har skapats.

int PyRefTracer_DESTROY

Värdet för parametern event till PyRefTracer-funktioner när ett Python-objekt har förstörts.

int PyRefTracer_SetTracer(PyRefTracer tracer, void *data)

Registrera en funktion för referensspårning. Funktionen kommer att anropas när en ny Python har skapats eller när ett objekt ska förstöras. Om data anges måste det vara en ogenomskinlig pekare som kommer att anges när spårningsfunktionen anropas. Returnera 0 vid framgång. Ställ in ett undantag och returnera -1 vid fel.

Observera att spårningsfunktioner inte får skapa Python-objekt inuti, annars kommer anropet att vara re-entrant. Spåraren får inte heller tömma något befintligt undantag eller skapa ett undantag. En thread state kommer att vara aktiv varje gång tracerfunktionen anropas.

Det måste finnas en attached thread state när denna funktion anropas.

Tillagd i version 3.13.

PyRefTracer PyRefTracer_GetTracer(void **data)

Hämtar den registrerade referensspårningsfunktionen och värdet på den opaka datapekaren som registrerades när PyRefTracer_SetTracer() anropades. Om ingen spårningsfunktion registrerades returnerar denna funktion NULL och sätter pekaren data till NULL.

Det måste finnas en attached thread state när denna funktion anropas.

Tillagd i version 3.13.

Avancerat stöd för felsökare

Dessa funktioner är endast avsedda att användas av avancerade felsökningsverktyg.

PyInterpreterState *PyInterpreterState_Head()

Returnerar tolkens statusobjekt längst upp i listan över alla sådana objekt.

PyInterpreterState *PyInterpreterState_Main()

Returnerar huvudtolkens statusobjekt.

PyInterpreterState *PyInterpreterState_Next(PyInterpreterState *interp)

Returnerar nästa tolktillståndsobjekt efter interp från listan över alla sådana objekt.

PyThreadState *PyInterpreterState_ThreadHead(PyInterpreterState *interp)

Returnerar pekaren till det första PyThreadState-objektet i listan över trådar som är associerade med tolken interp.

PyThreadState *PyThreadState_Next(PyThreadState *tstate)

Returnerar nästa trådtillståndsobjekt efter tstate från listan över alla sådana objekt som tillhör samma PyInterpreterState-objekt.

Tråd Stöd för lokal lagring

Python-tolken ger stöd på låg nivå för trådlokal lagring (TLS) som omsluter den underliggande inbyggda TLS-implementeringen för att stödja API:et för trådlokal lagring på Python-nivå (threading.local). CPythons API:er på C-nivå liknar de som erbjuds av pthreads och Windows: använd en trådnyckel och funktioner för att associera ett void*-värde per tråd.

En thread state behöver inte vara attached när dessa funktioner anropas; de kompletterar sin egen låsning.

Observera att Python.h inte innehåller deklarationen av TLS API:erna, du måste inkludera pythread.h för att använda trådlokal lagring.

Anteckning

Ingen av dessa API-funktioner hanterar minneshantering för void*-värdenas räkning. Du måste allokera och avallokera dem själv. Om void*-värdena råkar vara PyObject*, utför dessa funktioner inte heller refcount-operationer på dem.

API för trådspecifik lagring (TSS)

TSS API introduceras för att ersätta användningen av det befintliga TLS API inom CPython-tolken. Detta API använder en ny typ Py_tss_t istället för int för att representera trådnycklar.

Tillagd i version 3.7.

Se även

”Ett nytt C-API för trådlokal lagring i CPython” (PEP 539)

type Py_tss_t

Denna datastruktur representerar tillståndet för en trådnyckel, vars definition kan bero på den underliggande TLS-implementeringen, och den har ett internt fält som representerar nyckelns initialiseringstillstånd. Det finns inga offentliga medlemmar i denna struktur.

När Py_LIMITED_API inte är definierad, tillåts statisk allokering av denna typ genom Py_tss_NEEDS_INIT.

Py_tss_NEEDS_INIT

Detta makro expanderar till initialiseraren för Py_tss_t-variabler. Observera att detta makro inte kommer att definieras med Py_LIMITED_API.

Dynamisk allokering

Dynamisk allokering av Py_tss_t, krävs i tilläggsmoduler byggda med Py_LIMITED_API, där statisk allokering av denna typ inte är möjlig på grund av att dess implementation är ogenomskinlig vid byggtiden.

Py_tss_t *PyThread_tss_alloc()
En del av Stabil ABI sedan version 3.7.

Returnerar ett värde som är i samma tillstånd som ett värde som initierats med Py_tss_NEEDS_INIT, eller NULL om dynamisk allokering misslyckats.

void PyThread_tss_free(Py_tss_t *key)
En del av Stabil ABI sedan version 3.7.

Frigör den givna key som allokerats av PyThread_tss_alloc(), efter att först ha anropat PyThread_tss_delete() för att säkerställa att alla associerade trådlokaler har avallokerats. Detta är ett no-op om argumentet key är NULL.

Anteckning

En frigjord nyckel blir en hängande pekare. Du bör återställa nyckeln till NULL.

Metoder

Parametern key i dessa funktioner får inte vara NULL. Dessutom är beteendena hos PyThread_tss_set() och PyThread_tss_get() odefinierade om den givna Py_tss_t inte har initialiserats av PyThread_tss_create().

int PyThread_tss_is_created(Py_tss_t *key)
En del av Stabil ABI sedan version 3.7.

Returnerar ett värde som inte är noll om den angivna Py_tss_t har initialiserats av PyThread_tss_create().

int PyThread_tss_create(Py_tss_t *key)
En del av Stabil ABI sedan version 3.7.

Returnerar ett nollvärde vid lyckad initialisering av en TSS-nyckel. Beteendet är odefinierat om det värde som pekas ut av argumentet key inte initieras av Py_tss_NEEDS_INIT. Denna funktion kan anropas upprepade gånger på samma nyckel - att anropa den på en redan initialiserad nyckel är en no-op och returnerar omedelbart framgång.

void PyThread_tss_delete(Py_tss_t *key)
En del av Stabil ABI sedan version 3.7.

Förstör en TSS-nyckel för att glömma de värden som är associerade med nyckeln i alla trådar och ändra nyckelns initialiseringstillstånd till uninitialized. En förstörd nyckel kan initialiseras igen med PyThread_tss_create(). Den här funktionen kan anropas upprepade gånger på samma nyckel - att anropa den på en redan förstörd nyckel är inte möjligt.

int PyThread_tss_set(Py_tss_t *key, void *value)
En del av Stabil ABI sedan version 3.7.

Returnerar ett nollvärde för att indikera att ett void*-värde har associerats med en TSS-nyckel i den aktuella tråden. Varje tråd har en distinkt mappning av nyckeln till ett void*-värde.

void *PyThread_tss_get(Py_tss_t *key)
En del av Stabil ABI sedan version 3.7.

Returnerar det void*-värde som associeras med en TSS-nyckel i den aktuella tråden. Returnerar NULL om inget värde är associerat med nyckeln i den aktuella tråden.

API för lokal lagring av trådar (TLS)

Föråldrad sedan version 3.7: Detta API ersätts av Thread Specific Storage (TSS) API.

Anteckning

Den här versionen av API:et stöder inte plattformar där den ursprungliga TLS-nyckeln definieras på ett sätt som inte säkert kan kastas till int. På sådana plattformar kommer PyThread_create_key() att returnera omedelbart med en felstatus, och de andra TLS-funktionerna kommer alla att vara no-ops på sådana plattformar.

På grund av det kompatibilitetsproblem som nämns ovan bör denna version av API:et inte användas i ny kod.

int PyThread_create_key()
En del av Stabil ABI.
void PyThread_delete_key(int key)
En del av Stabil ABI.
int PyThread_set_key_value(int key, void *value)
En del av Stabil ABI.
void *PyThread_get_key_value(int key)
En del av Stabil ABI.
void PyThread_delete_key_value(int key)
En del av Stabil ABI.
void PyThread_ReInitTLS()
En del av Stabil ABI.

Synkroniseringsprimitiver

C-API tillhandahåller ett grundläggande lås med ömsesidig uteslutning.

type PyMutex

Ett ömsesidigt uteslutningslås. PyMutex bör initialiseras till noll för att representera det olåsta tillståndet. Till exempel:

PyMutex mutex = {0};

Instanser av PyMutex bör inte kopieras eller flyttas. Både innehållet och adressen i en PyMutex är meningsfulla och den måste ligga kvar på en fast, skrivbar plats i minnet.

Anteckning

En PyMutex upptar för närvarande en byte, men storleken bör betraktas som instabil. Storleken kan komma att ändras i framtida Python-utgåvor utan en utfasningsperiod.

Tillagd i version 3.13.

void PyMutex_Lock(PyMutex *m)

Låser mutex m. Om en annan tråd redan har låst den, kommer den anropande tråden att blockera tills mutexen låses upp. Under blockeringen kommer tråden tillfälligt att ta bort thread state om en sådan finns.

Tillagd i version 3.13.

void PyMutex_Unlock(PyMutex *m)

Lås upp mutex m. Mutex måste vara låst — annars kommer funktionen att utfärda ett fatalt fel.

Tillagd i version 3.13.

int PyMutex_IsLocked(PyMutex *m)

Returnerar icke-noll om mutex m för närvarande är låst, noll annars.

Anteckning

Den här funktionen är endast avsedd att användas i samband med påståenden och felsökning och bör inte användas för att fatta beslut om samtidighetskontroll, eftersom låsets tillstånd kan ändras omedelbart efter kontrollen.

Tillagd i version 3.14.

Python API för kritiska avsnitt

API:et för kritiska sektioner tillhandahåller ett lager för att undvika deadlock ovanpå lås per objekt för free-threaded CPython. De är avsedda att ersätta beroendet av global interpreter lock, och är no-ops i versioner av Python med global interpreter lock.

Critical sections are intended to be used for custom types implemented in C-API extensions. They should generally not be used with built-in types like list and dict because their public C-APIs already use critical sections internally, with the notable exception of PyDict_Next(), which requires critical section to be acquired externally.

Critical sections avoid deadlocks by implicitly suspending active critical sections, hence, they do not provide exclusive access such as provided by traditional locks like PyMutex. When a critical section is started, the per-object lock for the object is acquired. If the code executed inside the critical section calls C-API functions then it can suspend the critical section thereby releasing the per-object lock, so other threads can acquire the per-object lock for the same object.

Varianter som accepterar PyMutex-pekare i stället för Python-objekt finns också tillgängliga. Använd dessa varianter för att starta ett kritiskt avsnitt i en situation där det inte finns någon PyObject – till exempel när du arbetar med en C-typ som inte utökar eller omsluter PyObject men som ändå behöver anropa C API:et på ett sätt som kan leda till dödlägen.

De funktioner och strukturer som används av makron är exponerade för fall där C-makron inte är tillgängliga. De bör endast användas som i de givna makroexpansionerna. Observera att strukturernas storlek och innehåll kan komma att ändras i framtida Python-versioner.

Anteckning

Operationer som behöver låsa två objekt samtidigt måste använda Py_BEGIN_CRITICAL_SECTION2. Du kan inte använda nästlade kritiska avsnitt för att låsa mer än ett objekt samtidigt, eftersom det inre kritiska avsnittet kan avbryta de yttre kritiska avsnitten. Detta API tillhandahåller inte något sätt att låsa mer än två objekt samtidigt.

Exempel på användning:

static PyObject *
set_field(MyObject *self, PyObject *value)
{
   Py_BEGIN_CRITICAL_SECTION(self);
   Py_SETREF(self->field, Py_XNewRef(value));
   Py_END_CRITICAL_SECTION();
   Py_RETURN_NONE;
}

I exemplet ovan anropar Py_SETREF Py_DECREF, som kan anropa godtycklig kod via ett objekts deallokeringsfunktion. API:et för kritiska sektioner undviker potentiella dödlägen på grund av reentrancy och låsordning genom att tillåta runtime att tillfälligt avbryta den kritiska sektionen om koden som utlöses av finalizer blockerar och anropar PyEval_SaveThread().

Py_BEGIN_CRITICAL_SECTION(op)

Förvärvar låset per objekt för objektet op och påbörjar ett kritiskt avsnitt.

I den fritt trådade versionen expanderar detta makro till:

{
    PyCriticalSection _py_cs;
    PyCriticalSection_Begin(&_py_cs, (PyObject*)(op))

I standardutförandet expanderar detta makro till {.

Tillagd i version 3.13.

Py_BEGIN_CRITICAL_SECTION_MUTEX(m)

Låser mutex m och påbörjar en kritisk sektion.

I den fritt trådade versionen expanderar detta makro till:

{
     PyCriticalSection _py_cs;
     PyCriticalSection_BeginMutex(&_py_cs, m)

Observera att till skillnad från Py_BEGIN_CRITICAL_SECTION finns det ingen cast för argumentet i makrot - det måste vara en PyMutex-pekare.

I standardutförandet expanderar detta makro till {.

Tillagd i version 3.14.

Py_END_CRITICAL_SECTION()

Avslutar det kritiska avsnittet och frigör låset per objekt.

I den fritt trådade versionen expanderar detta makro till:

    PyCriticalSection_End(&_py_cs);
}

I standardutförandet expanderar detta makro till }.

Tillagd i version 3.13.

Py_BEGIN_CRITICAL_SECTION2(a, b)

Förvärvar låsen per objekt för objekten a och b och påbörjar en kritisk sektion. Låsen förvärvas i en konsekvent ordning (lägsta adress först) för att undvika låsningsdödlägen.

I den fritt trådade versionen expanderar detta makro till:

{
    PyCriticalSection2 _py_cs2;
    PyCriticalSection2_Begin(&_py_cs2, (PyObject*)(a), (PyObject*)(b))

I standardutförandet expanderar detta makro till {.

Tillagd i version 3.13.

Py_BEGIN_CRITICAL_SECTION2_MUTEX(m1, m2)

Låser mutexarna m1 och m2 och påbörjar en kritisk sektion.

I den fritt trådade versionen expanderar detta makro till:

{
     PyCriticalSection2 _py_cs2;
     PyCriticalSection2_BeginMutex(&_py_cs2, m1, m2)

Observera att till skillnad från Py_BEGIN_CRITICAL_SECTION2 finns det ingen cast för argumenten i makrot - de måste vara PyMutex-pekare.

I standardutförandet expanderar detta makro till {.

Tillagd i version 3.14.

Py_END_CRITICAL_SECTION2()

Avslutar det kritiska avsnittet och frigör låsen per objekt.

I den fritt trådade versionen expanderar detta makro till:

    PyCriticalSection2_End(&_py_cs2);
}

I standardutförandet expanderar detta makro till }.

Tillagd i version 3.13.