# SOME DESCRIPTIVE TITLE. # Copyright (C) 2001 Python Software Foundation # This file is distributed under the same license as the Python package. # FIRST AUTHOR , YEAR. # # Translators: # oon arfiandwi , 2024 # #, fuzzy msgid "" msgstr "" "Project-Id-Version: Python 3.14\n" "Report-Msgid-Bugs-To: \n" "POT-Creation-Date: 2025-05-09 14:19+0000\n" "PO-Revision-Date: 2021-06-28 00:49+0000\n" "Last-Translator: oon arfiandwi , 2024\n" "Language-Team: Indonesian (https://app.transifex.com/python-doc/teams/5390/id/)\n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" "Language: id\n" "Plural-Forms: nplurals=1; plural=0;\n" #: ../../c-api/init.rst:8 msgid "Initialization, Finalization, and Threads" msgstr "" #: ../../c-api/init.rst:10 msgid "" "See :ref:`Python Initialization Configuration ` for details on " "how to configure the interpreter prior to initialization." msgstr "" #: ../../c-api/init.rst:16 msgid "Before Python Initialization" msgstr "" #: ../../c-api/init.rst:18 msgid "" "In an application embedding Python, the :c:func:`Py_Initialize` function " "must be called before using any other Python/C API functions; with the " "exception of a few functions and the :ref:`global configuration variables " "`." msgstr "" #: ../../c-api/init.rst:23 msgid "" "The following functions can be safely called before Python is initialized:" msgstr "" #: ../../c-api/init.rst:25 msgid "Functions that initialize the interpreter:" msgstr "" #: ../../c-api/init.rst:27 msgid ":c:func:`Py_Initialize`" msgstr "" #: ../../c-api/init.rst:28 msgid ":c:func:`Py_InitializeEx`" msgstr "" #: ../../c-api/init.rst:29 msgid ":c:func:`Py_InitializeFromConfig`" msgstr ":c:func:`Py_InitializeFromConfig`" #: ../../c-api/init.rst:30 msgid ":c:func:`Py_BytesMain`" msgstr ":c:func:`Py_BytesMain`" #: ../../c-api/init.rst:31 msgid ":c:func:`Py_Main`" msgstr "" #: ../../c-api/init.rst:32 msgid "the runtime pre-initialization functions covered in :ref:`init-config`" msgstr "" #: ../../c-api/init.rst:34 msgid "Configuration functions:" msgstr "" #: ../../c-api/init.rst:36 msgid ":c:func:`PyImport_AppendInittab`" msgstr ":c:func:`PyImport_AppendInittab`" #: ../../c-api/init.rst:37 msgid ":c:func:`PyImport_ExtendInittab`" msgstr ":c:func:`PyImport_ExtendInittab`" #: ../../c-api/init.rst:38 msgid ":c:func:`!PyInitFrozenExtensions`" msgstr "" #: ../../c-api/init.rst:39 msgid ":c:func:`PyMem_SetAllocator`" msgstr ":c:func:`PyMem_SetAllocator`" #: ../../c-api/init.rst:40 msgid ":c:func:`PyMem_SetupDebugHooks`" msgstr ":c:func:`PyMem_SetupDebugHooks`" #: ../../c-api/init.rst:41 msgid ":c:func:`PyObject_SetArenaAllocator`" msgstr ":c:func:`PyObject_SetArenaAllocator`" #: ../../c-api/init.rst:42 msgid ":c:func:`Py_SetProgramName`" msgstr ":c:func:`Py_SetProgramName`" #: ../../c-api/init.rst:43 msgid ":c:func:`Py_SetPythonHome`" msgstr ":c:func:`Py_SetPythonHome`" #: ../../c-api/init.rst:44 msgid ":c:func:`PySys_ResetWarnOptions`" msgstr ":c:func:`PySys_ResetWarnOptions`" #: ../../c-api/init.rst:45 msgid "the configuration functions covered in :ref:`init-config`" msgstr "" #: ../../c-api/init.rst:47 msgid "Informative functions:" msgstr "" #: ../../c-api/init.rst:49 ../../c-api/init.rst:57 msgid ":c:func:`Py_IsInitialized`" msgstr ":c:func:`Py_IsInitialized`" #: ../../c-api/init.rst:50 msgid ":c:func:`PyMem_GetAllocator`" msgstr ":c:func:`PyMem_GetAllocator`" #: ../../c-api/init.rst:51 msgid ":c:func:`PyObject_GetArenaAllocator`" msgstr ":c:func:`PyObject_GetArenaAllocator`" #: ../../c-api/init.rst:52 msgid ":c:func:`Py_GetBuildInfo`" msgstr ":c:func:`Py_GetBuildInfo`" #: ../../c-api/init.rst:53 msgid ":c:func:`Py_GetCompiler`" msgstr ":c:func:`Py_GetCompiler`" #: ../../c-api/init.rst:54 msgid ":c:func:`Py_GetCopyright`" msgstr ":c:func:`Py_GetCopyright`" #: ../../c-api/init.rst:55 msgid ":c:func:`Py_GetPlatform`" msgstr ":c:func:`Py_GetPlatform`" #: ../../c-api/init.rst:56 msgid ":c:func:`Py_GetVersion`" msgstr ":c:func:`Py_GetVersion`" #: ../../c-api/init.rst:59 msgid "Utilities:" msgstr "" #: ../../c-api/init.rst:61 msgid ":c:func:`Py_DecodeLocale`" msgstr ":c:func:`Py_DecodeLocale`" #: ../../c-api/init.rst:62 msgid "" "the status reporting and utility functions covered in :ref:`init-config`" msgstr "" #: ../../c-api/init.rst:64 msgid "Memory allocators:" msgstr "" #: ../../c-api/init.rst:66 msgid ":c:func:`PyMem_RawMalloc`" msgstr ":c:func:`PyMem_RawMalloc`" #: ../../c-api/init.rst:67 msgid ":c:func:`PyMem_RawRealloc`" msgstr ":c:func:`PyMem_RawRealloc`" #: ../../c-api/init.rst:68 msgid ":c:func:`PyMem_RawCalloc`" msgstr ":c:func:`PyMem_RawCalloc`" #: ../../c-api/init.rst:69 msgid ":c:func:`PyMem_RawFree`" msgstr ":c:func:`PyMem_RawFree`" #: ../../c-api/init.rst:71 msgid "Synchronization:" msgstr "" #: ../../c-api/init.rst:73 msgid ":c:func:`PyMutex_Lock`" msgstr "" #: ../../c-api/init.rst:74 msgid ":c:func:`PyMutex_Unlock`" msgstr "" #: ../../c-api/init.rst:78 msgid "" "Despite their apparent similarity to some of the functions listed above, the" " following functions **should not be called** before the interpreter has " "been initialized: :c:func:`Py_EncodeLocale`, :c:func:`Py_GetPath`, " ":c:func:`Py_GetPrefix`, :c:func:`Py_GetExecPrefix`, " ":c:func:`Py_GetProgramFullPath`, :c:func:`Py_GetPythonHome`, " ":c:func:`Py_GetProgramName`, :c:func:`PyEval_InitThreads`, and " ":c:func:`Py_RunMain`." msgstr "" #: ../../c-api/init.rst:90 msgid "Global configuration variables" msgstr "" #: ../../c-api/init.rst:92 msgid "" "Python has variables for the global configuration to control different " "features and options. By default, these flags are controlled by " ":ref:`command line options `." msgstr "" #: ../../c-api/init.rst:96 msgid "" "When a flag is set by an option, the value of the flag is the number of " "times that the option was set. For example, ``-b`` sets " ":c:data:`Py_BytesWarningFlag` to 1 and ``-bb`` sets " ":c:data:`Py_BytesWarningFlag` to 2." msgstr "" #: ../../c-api/init.rst:102 msgid "" "This API is kept for backward compatibility: setting " ":c:member:`PyConfig.bytes_warning` should be used instead, see :ref:`Python " "Initialization Configuration `." msgstr "" #: ../../c-api/init.rst:106 msgid "" "Issue a warning when comparing :class:`bytes` or :class:`bytearray` with " ":class:`str` or :class:`bytes` with :class:`int`. Issue an error if greater" " or equal to ``2``." msgstr "" #: ../../c-api/init.rst:110 msgid "Set by the :option:`-b` option." msgstr "" #: ../../c-api/init.rst:116 msgid "" "This API is kept for backward compatibility: setting " ":c:member:`PyConfig.parser_debug` should be used instead, see :ref:`Python " "Initialization Configuration `." msgstr "" #: ../../c-api/init.rst:120 msgid "" "Turn on parser debugging output (for expert only, depending on compilation " "options)." msgstr "" #: ../../c-api/init.rst:123 msgid "" "Set by the :option:`-d` option and the :envvar:`PYTHONDEBUG` environment " "variable." msgstr "" #: ../../c-api/init.rst:130 msgid "" "This API is kept for backward compatibility: setting " ":c:member:`PyConfig.write_bytecode` should be used instead, see :ref:`Python" " Initialization Configuration `." msgstr "" #: ../../c-api/init.rst:134 msgid "" "If set to non-zero, Python won't try to write ``.pyc`` files on the import " "of source modules." msgstr "" #: ../../c-api/init.rst:137 msgid "" "Set by the :option:`-B` option and the :envvar:`PYTHONDONTWRITEBYTECODE` " "environment variable." msgstr "" #: ../../c-api/init.rst:144 msgid "" "This API is kept for backward compatibility: setting " ":c:member:`PyConfig.pathconfig_warnings` should be used instead, see " ":ref:`Python Initialization Configuration `." msgstr "" #: ../../c-api/init.rst:148 msgid "" "Suppress error messages when calculating the module search path in " ":c:func:`Py_GetPath`." msgstr "" #: ../../c-api/init.rst:151 msgid "Private flag used by ``_freeze_module`` and ``frozenmain`` programs." msgstr "" #: ../../c-api/init.rst:157 msgid "" "This API is kept for backward compatibility: setting " ":c:member:`PyConfig.hash_seed` and :c:member:`PyConfig.use_hash_seed` should" " be used instead, see :ref:`Python Initialization Configuration `." msgstr "" #: ../../c-api/init.rst:162 msgid "" "Set to ``1`` if the :envvar:`PYTHONHASHSEED` environment variable is set to " "a non-empty string." msgstr "" #: ../../c-api/init.rst:165 msgid "" "If the flag is non-zero, read the :envvar:`PYTHONHASHSEED` environment " "variable to initialize the secret hash seed." msgstr "" #: ../../c-api/init.rst:172 msgid "" "This API is kept for backward compatibility: setting " ":c:member:`PyConfig.use_environment` should be used instead, see " ":ref:`Python Initialization Configuration `." msgstr "" #: ../../c-api/init.rst:176 msgid "" "Ignore all :envvar:`!PYTHON*` environment variables, e.g. " ":envvar:`PYTHONPATH` and :envvar:`PYTHONHOME`, that might be set." msgstr "" #: ../../c-api/init.rst:179 msgid "Set by the :option:`-E` and :option:`-I` options." msgstr "" #: ../../c-api/init.rst:185 msgid "" "This API is kept for backward compatibility: setting " ":c:member:`PyConfig.inspect` should be used instead, see :ref:`Python " "Initialization Configuration `." msgstr "" #: ../../c-api/init.rst:189 msgid "" "When a script is passed as first argument or the :option:`-c` option is " "used, enter interactive mode after executing the script or the command, even" " when :data:`sys.stdin` does not appear to be a terminal." msgstr "" #: ../../c-api/init.rst:193 msgid "" "Set by the :option:`-i` option and the :envvar:`PYTHONINSPECT` environment " "variable." msgstr "" #: ../../c-api/init.rst:200 msgid "" "This API is kept for backward compatibility: setting " ":c:member:`PyConfig.interactive` should be used instead, see :ref:`Python " "Initialization Configuration `." msgstr "" #: ../../c-api/init.rst:204 msgid "Set by the :option:`-i` option." msgstr "" #: ../../c-api/init.rst:210 msgid "" "This API is kept for backward compatibility: setting " ":c:member:`PyConfig.isolated` should be used instead, see :ref:`Python " "Initialization Configuration `." msgstr "" #: ../../c-api/init.rst:214 msgid "" "Run Python in isolated mode. In isolated mode :data:`sys.path` contains " "neither the script's directory nor the user's site-packages directory." msgstr "" #: ../../c-api/init.rst:217 msgid "Set by the :option:`-I` option." msgstr "" #: ../../c-api/init.rst:225 msgid "" "This API is kept for backward compatibility: setting " ":c:member:`PyPreConfig.legacy_windows_fs_encoding` should be used instead, " "see :ref:`Python Initialization Configuration `." msgstr "" #: ../../c-api/init.rst:229 msgid "" "If the flag is non-zero, use the ``mbcs`` encoding with ``replace`` error " "handler, instead of the UTF-8 encoding with ``surrogatepass`` error handler," " for the :term:`filesystem encoding and error handler`." msgstr "" #: ../../c-api/init.rst:233 msgid "" "Set to ``1`` if the :envvar:`PYTHONLEGACYWINDOWSFSENCODING` environment " "variable is set to a non-empty string." msgstr "" #: ../../c-api/init.rst:236 msgid "See :pep:`529` for more details." msgstr "Lihat :pep:`529` untuk lebih detail." #: ../../c-api/init.rst:238 ../../c-api/init.rst:256 msgid "Availability" msgstr "" #: ../../c-api/init.rst:244 msgid "" "This API is kept for backward compatibility: setting " ":c:member:`PyConfig.legacy_windows_stdio` should be used instead, see " ":ref:`Python Initialization Configuration `." msgstr "" #: ../../c-api/init.rst:248 msgid "" "If the flag is non-zero, use :class:`io.FileIO` instead of " ":class:`!io._WindowsConsoleIO` for :mod:`sys` standard streams." msgstr "" #: ../../c-api/init.rst:251 msgid "" "Set to ``1`` if the :envvar:`PYTHONLEGACYWINDOWSSTDIO` environment variable " "is set to a non-empty string." msgstr "" #: ../../c-api/init.rst:254 msgid "See :pep:`528` for more details." msgstr "" #: ../../c-api/init.rst:262 msgid "" "This API is kept for backward compatibility: setting " ":c:member:`PyConfig.site_import` should be used instead, see :ref:`Python " "Initialization Configuration `." msgstr "" #: ../../c-api/init.rst:266 msgid "" "Disable the import of the module :mod:`site` and the site-dependent " "manipulations of :data:`sys.path` that it entails. Also disable these " "manipulations if :mod:`site` is explicitly imported later (call " ":func:`site.main` if you want them to be triggered)." msgstr "" #: ../../c-api/init.rst:271 msgid "Set by the :option:`-S` option." msgstr "" #: ../../c-api/init.rst:277 msgid "" "This API is kept for backward compatibility: setting " ":c:member:`PyConfig.user_site_directory` should be used instead, see " ":ref:`Python Initialization Configuration `." msgstr "" #: ../../c-api/init.rst:281 msgid "" "Don't add the :data:`user site-packages directory ` to " ":data:`sys.path`." msgstr "" #: ../../c-api/init.rst:284 msgid "" "Set by the :option:`-s` and :option:`-I` options, and the " ":envvar:`PYTHONNOUSERSITE` environment variable." msgstr "" #: ../../c-api/init.rst:291 msgid "" "This API is kept for backward compatibility: setting " ":c:member:`PyConfig.optimization_level` should be used instead, see " ":ref:`Python Initialization Configuration `." msgstr "" #: ../../c-api/init.rst:295 msgid "" "Set by the :option:`-O` option and the :envvar:`PYTHONOPTIMIZE` environment " "variable." msgstr "" #: ../../c-api/init.rst:302 msgid "" "This API is kept for backward compatibility: setting " ":c:member:`PyConfig.quiet` should be used instead, see :ref:`Python " "Initialization Configuration `." msgstr "" #: ../../c-api/init.rst:306 msgid "" "Don't display the copyright and version messages even in interactive mode." msgstr "" #: ../../c-api/init.rst:308 msgid "Set by the :option:`-q` option." msgstr "" #: ../../c-api/init.rst:316 msgid "" "This API is kept for backward compatibility: setting " ":c:member:`PyConfig.buffered_stdio` should be used instead, see :ref:`Python" " Initialization Configuration `." msgstr "" #: ../../c-api/init.rst:320 msgid "Force the stdout and stderr streams to be unbuffered." msgstr "" #: ../../c-api/init.rst:322 msgid "" "Set by the :option:`-u` option and the :envvar:`PYTHONUNBUFFERED` " "environment variable." msgstr "" #: ../../c-api/init.rst:329 msgid "" "This API is kept for backward compatibility: setting " ":c:member:`PyConfig.verbose` should be used instead, see :ref:`Python " "Initialization Configuration `." msgstr "" #: ../../c-api/init.rst:333 msgid "" "Print a message each time a module is initialized, showing the place " "(filename or built-in module) from which it is loaded. If greater or equal " "to ``2``, print a message for each file that is checked for when searching " "for a module. Also provides information on module cleanup at exit." msgstr "" #: ../../c-api/init.rst:338 msgid "" "Set by the :option:`-v` option and the :envvar:`PYTHONVERBOSE` environment " "variable." msgstr "" #: ../../c-api/init.rst:345 msgid "Initializing and finalizing the interpreter" msgstr "" #: ../../c-api/init.rst:360 msgid "" "Initialize the Python interpreter. In an application embedding Python, " "this should be called before using any other Python/C API functions; see " ":ref:`Before Python Initialization ` for the few exceptions." msgstr "" #: ../../c-api/init.rst:364 msgid "" "This initializes the table of loaded modules (``sys.modules``), and creates " "the fundamental modules :mod:`builtins`, :mod:`__main__` and :mod:`sys`. It " "also initializes the module search path (``sys.path``). It does not set " "``sys.argv``; use the :ref:`Python Initialization Configuration ` API for that. This is a no-op when called for a second time " "(without calling :c:func:`Py_FinalizeEx` first). There is no return value; " "it is a fatal error if the initialization fails." msgstr "" #: ../../c-api/init.rst:372 ../../c-api/init.rst:386 msgid "" "Use :c:func:`Py_InitializeFromConfig` to customize the :ref:`Python " "Initialization Configuration `." msgstr "" #: ../../c-api/init.rst:376 msgid "" "On Windows, changes the console mode from ``O_TEXT`` to ``O_BINARY``, which " "will also affect non-Python uses of the console using the C Runtime." msgstr "" #: ../../c-api/init.rst:382 msgid "" "This function works like :c:func:`Py_Initialize` if *initsigs* is ``1``. If " "*initsigs* is ``0``, it skips initialization registration of signal " "handlers, which may be useful when CPython is embedded as part of a larger " "application." msgstr "" #: ../../c-api/init.rst:392 msgid "" "Initialize Python from *config* configuration, as described in :ref:`init-" "from-config`." msgstr "" #: ../../c-api/init.rst:395 msgid "" "See the :ref:`init-config` section for details on pre-initializing the " "interpreter, populating the runtime configuration structure, and querying " "the returned status structure." msgstr "" #: ../../c-api/init.rst:402 msgid "" "Return true (nonzero) when the Python interpreter has been initialized, " "false (zero) if not. After :c:func:`Py_FinalizeEx` is called, this returns " "false until :c:func:`Py_Initialize` is called again." msgstr "" #: ../../c-api/init.rst:409 msgid "" "Return true (non-zero) if the main Python interpreter is :term:`shutting " "down `. Return false (zero) otherwise." msgstr "" #: ../../c-api/init.rst:417 msgid "" "Undo all initializations made by :c:func:`Py_Initialize` and subsequent use " "of Python/C API functions, and destroy all sub-interpreters (see " ":c:func:`Py_NewInterpreter` below) that were created and not yet destroyed " "since the last call to :c:func:`Py_Initialize`. This is a no-op when called" " for a second time (without calling :c:func:`Py_Initialize` again first)." msgstr "" #: ../../c-api/init.rst:423 msgid "" "Since this is the reverse of :c:func:`Py_Initialize`, it should be called in" " the same thread with the same interpreter active. That means the main " "thread and the main interpreter. This should never be called while " ":c:func:`Py_RunMain` is running." msgstr "" #: ../../c-api/init.rst:428 msgid "" "Normally the return value is ``0``. If there were errors during finalization" " (flushing buffered data), ``-1`` is returned." msgstr "" #: ../../c-api/init.rst:432 msgid "" "Note that Python will do a best effort at freeing all memory allocated by " "the Python interpreter. Therefore, any C-Extension should make sure to " "correctly clean up all of the preveiously allocated PyObjects before using " "them in subsequent calls to :c:func:`Py_Initialize`. Otherwise it could " "introduce vulnerabilities and incorrect behavior." msgstr "" #: ../../c-api/init.rst:438 msgid "" "This function is provided for a number of reasons. An embedding application" " might want to restart Python without having to restart the application " "itself. An application that has loaded the Python interpreter from a " "dynamically loadable library (or DLL) might want to free all memory " "allocated by Python before unloading the DLL. During a hunt for memory leaks" " in an application a developer might want to free all memory allocated by " "Python before exiting from the application." msgstr "" #: ../../c-api/init.rst:446 msgid "" "**Bugs and caveats:** The destruction of modules and objects in modules is " "done in random order; this may cause destructors (:meth:`~object.__del__` " "methods) to fail when they depend on other objects (even functions) or " "modules. Dynamically loaded extension modules loaded by Python are not " "unloaded. Small amounts of memory allocated by the Python interpreter may " "not be freed (if you find a leak, please report it). Memory tied up in " "circular references between objects is not freed. Interned strings will all" " be deallocated regardless of their reference count. Some memory allocated " "by extension modules may not be freed. Some extensions may not work " "properly if their initialization routine is called more than once; this can " "happen if an application calls :c:func:`Py_Initialize` and " ":c:func:`Py_FinalizeEx` more than once. :c:func:`Py_FinalizeEx` must not be" " called recursively from within itself. Therefore, it must not be called by" " any code that may be run as part of the interpreter shutdown process, such " "as :py:mod:`atexit` handlers, object finalizers, or any code that may be run" " while flushing the stdout and stderr files." msgstr "" #: ../../c-api/init.rst:462 msgid "" "Raises an :ref:`auditing event ` " "``cpython._PySys_ClearAuditHooks`` with no arguments." msgstr "" #: ../../c-api/init.rst:469 msgid "" "This is a backwards-compatible version of :c:func:`Py_FinalizeEx` that " "disregards the return value." msgstr "" #: ../../c-api/init.rst:475 msgid "" "Similar to :c:func:`Py_Main` but *argv* is an array of bytes strings, " "allowing the calling application to delegate the text decoding step to the " "CPython runtime." msgstr "" #: ../../c-api/init.rst:484 msgid "" "The main program for the standard interpreter, encapsulating a full " "initialization/finalization cycle, as well as additional behaviour to " "implement reading configurations settings from the environment and command " "line, and then executing ``__main__`` in accordance with :ref:`using-on-" "cmdline`." msgstr "" #: ../../c-api/init.rst:490 msgid "" "This is made available for programs which wish to support the full CPython " "command line interface, rather than just embedding a Python runtime in a " "larger application." msgstr "" #: ../../c-api/init.rst:494 msgid "" "The *argc* and *argv* parameters are similar to those which are passed to a " "C program's :c:func:`main` function, except that the *argv* entries are " "first converted to ``wchar_t`` using :c:func:`Py_DecodeLocale`. It is also " "important to note that the argument list entries may be modified to point to" " strings other than those passed in (however, the contents of the strings " "pointed to by the argument list are not modified)." msgstr "" #: ../../c-api/init.rst:501 msgid "" "The return value will be ``0`` if the interpreter exits normally (i.e., " "without an exception), ``1`` if the interpreter exits due to an exception, " "or ``2`` if the argument list does not represent a valid Python command " "line." msgstr "" #: ../../c-api/init.rst:506 msgid "" "Note that if an otherwise unhandled :exc:`SystemExit` is raised, this " "function will not return ``1``, but exit the process, as long as " "``Py_InspectFlag`` is not set. If ``Py_InspectFlag`` is set, execution will " "drop into the interactive Python prompt, at which point a second otherwise " "unhandled :exc:`SystemExit` will still exit the process, while any other " "means of exiting will set the return value as described above." msgstr "" #: ../../c-api/init.rst:513 msgid "" "In terms of the CPython runtime configuration APIs documented in the " ":ref:`runtime configuration ` section (and without accounting " "for error handling), ``Py_Main`` is approximately equivalent to::" msgstr "" #: ../../c-api/init.rst:517 msgid "" "PyConfig config;\n" "PyConfig_InitPythonConfig(&config);\n" "PyConfig_SetArgv(&config, argc, argv);\n" "Py_InitializeFromConfig(&config);\n" "PyConfig_Clear(&config);\n" "\n" "Py_RunMain();" msgstr "" #: ../../c-api/init.rst:525 msgid "" "In normal usage, an embedding application will call this function *instead* " "of calling :c:func:`Py_Initialize`, :c:func:`Py_InitializeEx` or " ":c:func:`Py_InitializeFromConfig` directly, and all settings will be applied" " as described elsewhere in this documentation. If this function is instead " "called *after* a preceding runtime initialization API call, then exactly " "which environmental and command line configuration settings will be updated " "is version dependent (as it depends on which settings correctly support " "being modified after they have already been set once when the runtime was " "first initialized)." msgstr "" #: ../../c-api/init.rst:538 msgid "Executes the main module in a fully configured CPython runtime." msgstr "" #: ../../c-api/init.rst:540 msgid "" "Executes the command (:c:member:`PyConfig.run_command`), the script " "(:c:member:`PyConfig.run_filename`) or the module " "(:c:member:`PyConfig.run_module`) specified on the command line or in the " "configuration. If none of these values are set, runs the interactive Python " "prompt (REPL) using the ``__main__`` module's global namespace." msgstr "" #: ../../c-api/init.rst:546 msgid "" "If :c:member:`PyConfig.inspect` is not set (the default), the return value " "will be ``0`` if the interpreter exits normally (that is, without raising an" " exception), or ``1`` if the interpreter exits due to an exception. If an " "otherwise unhandled :exc:`SystemExit` is raised, the function will " "immediately exit the process instead of returning ``1``." msgstr "" #: ../../c-api/init.rst:552 msgid "" "If :c:member:`PyConfig.inspect` is set (such as when the :option:`-i` option" " is used), rather than returning when the interpreter exits, execution will " "instead resume in an interactive Python prompt (REPL) using the ``__main__``" " module's global namespace. If the interpreter exited with an exception, it " "is immediately raised in the REPL session. The function return value is then" " determined by the way the *REPL session* terminates: returning ``0`` if the" " session terminates without raising an unhandled exception, exiting " "immediately for an unhandled :exc:`SystemExit`, and returning ``1`` for any " "other unhandled exception." msgstr "" #: ../../c-api/init.rst:562 msgid "" "This function always finalizes the Python interpreter regardless of whether " "it returns a value or immediately exits the process due to an unhandled " ":exc:`SystemExit` exception." msgstr "" #: ../../c-api/init.rst:566 msgid "" "See :ref:`Python Configuration ` for an example of a " "customized Python that always runs in isolated mode using " ":c:func:`Py_RunMain`." msgstr "" #: ../../c-api/init.rst:572 msgid "" "Register an :mod:`atexit` callback for the target interpreter *interp*. This" " is similar to :c:func:`Py_AtExit`, but takes an explicit interpreter and " "data pointer for the callback." msgstr "" #: ../../c-api/init.rst:576 msgid "There must be an :term:`attached thread state` for *interp*." msgstr "" #: ../../c-api/init.rst:581 msgid "Process-wide parameters" msgstr "" #: ../../c-api/init.rst:591 msgid "" "This API is kept for backward compatibility: setting " ":c:member:`PyConfig.program_name` should be used instead, see :ref:`Python " "Initialization Configuration `." msgstr "" #: ../../c-api/init.rst:595 msgid "" "This function should be called before :c:func:`Py_Initialize` is called for " "the first time, if it is called at all. It tells the interpreter the value " "of the ``argv[0]`` argument to the :c:func:`main` function of the program " "(converted to wide characters). This is used by :c:func:`Py_GetPath` and " "some other functions below to find the Python run-time libraries relative to" " the interpreter executable. The default value is ``'python'``. The " "argument should point to a zero-terminated wide character string in static " "storage whose contents will not change for the duration of the program's " "execution. No code in the Python interpreter will change the contents of " "this storage." msgstr "" #: ../../c-api/init.rst:606 ../../c-api/init.rst:854 ../../c-api/init.rst:890 #: ../../c-api/init.rst:916 msgid "" "Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a " ":c:expr:`wchar_t*` string." msgstr "" #: ../../c-api/init.rst:614 msgid "" "Return the program name set with :c:member:`PyConfig.program_name`, or the " "default. The returned string points into static storage; the caller should " "not modify its value." msgstr "" #: ../../c-api/init.rst:618 ../../c-api/init.rst:641 ../../c-api/init.rst:689 #: ../../c-api/init.rst:713 ../../c-api/init.rst:740 ../../c-api/init.rst:928 msgid "" "This function should not be called before :c:func:`Py_Initialize`, otherwise" " it returns ``NULL``." msgstr "" #: ../../c-api/init.rst:621 ../../c-api/init.rst:644 ../../c-api/init.rst:692 #: ../../c-api/init.rst:716 ../../c-api/init.rst:745 ../../c-api/init.rst:931 msgid "It now returns ``NULL`` if called before :c:func:`Py_Initialize`." msgstr "" #: ../../c-api/init.rst:624 ../../c-api/init.rst:719 msgid "" "Use :c:func:`PyConfig_Get(\"executable\") ` " "(:data:`sys.executable`) instead." msgstr "" #: ../../c-api/init.rst:631 msgid "" "Return the *prefix* for installed platform-independent files. This is " "derived through a number of complicated rules from the program name set with" " :c:member:`PyConfig.program_name` and some environment variables; for " "example, if the program name is ``'/usr/local/bin/python'``, the prefix is " "``'/usr/local'``. The returned string points into static storage; the caller" " should not modify its value. This corresponds to the :makevar:`prefix` " "variable in the top-level :file:`Makefile` and the :option:`--prefix` " "argument to the :program:`configure` script at build time. The value is " "available to Python code as ``sys.base_prefix``. It is only useful on Unix." " See also the next function." msgstr "" #: ../../c-api/init.rst:647 msgid "" "Use :c:func:`PyConfig_Get(\"base_prefix\") ` " "(:data:`sys.base_prefix`) instead. Use :c:func:`PyConfig_Get(\"prefix\") " "` (:data:`sys.prefix`) if :ref:`virtual environments ` need to be handled." msgstr "" #: ../../c-api/init.rst:656 msgid "" "Return the *exec-prefix* for installed platform-*dependent* files. This is " "derived through a number of complicated rules from the program name set with" " :c:member:`PyConfig.program_name` and some environment variables; for " "example, if the program name is ``'/usr/local/bin/python'``, the exec-prefix" " is ``'/usr/local'``. The returned string points into static storage; the " "caller should not modify its value. This corresponds to the " ":makevar:`exec_prefix` variable in the top-level :file:`Makefile` and the " "``--exec-prefix`` argument to the :program:`configure` script at build " "time. The value is available to Python code as ``sys.base_exec_prefix``. " "It is only useful on Unix." msgstr "" #: ../../c-api/init.rst:667 msgid "" "Background: The exec-prefix differs from the prefix when platform dependent " "files (such as executables and shared libraries) are installed in a " "different directory tree. In a typical installation, platform dependent " "files may be installed in the :file:`/usr/local/plat` subtree while platform" " independent may be installed in :file:`/usr/local`." msgstr "" #: ../../c-api/init.rst:673 msgid "" "Generally speaking, a platform is a combination of hardware and software " "families, e.g. Sparc machines running the Solaris 2.x operating system are " "considered the same platform, but Intel machines running Solaris 2.x are " "another platform, and Intel machines running Linux are yet another platform." " Different major revisions of the same operating system generally also form" " different platforms. Non-Unix operating systems are a different story; the" " installation strategies on those systems are so different that the prefix " "and exec-prefix are meaningless, and set to the empty string. Note that " "compiled Python bytecode files are platform independent (but not independent" " from the Python version by which they were compiled!)." msgstr "" #: ../../c-api/init.rst:684 msgid "" "System administrators will know how to configure the :program:`mount` or " ":program:`automount` programs to share :file:`/usr/local` between platforms " "while having :file:`/usr/local/plat` be a different filesystem for each " "platform." msgstr "" #: ../../c-api/init.rst:695 msgid "" "Use :c:func:`PyConfig_Get(\"base_exec_prefix\") ` " "(:data:`sys.base_exec_prefix`) instead. Use " ":c:func:`PyConfig_Get(\"exec_prefix\") ` " "(:data:`sys.exec_prefix`) if :ref:`virtual environments ` need to " "be handled." msgstr "" #: ../../c-api/init.rst:707 msgid "" "Return the full program name of the Python executable; this is computed as " "a side-effect of deriving the default module search path from the program " "name (set by :c:member:`PyConfig.program_name`). The returned string points " "into static storage; the caller should not modify its value. The value is " "available to Python code as ``sys.executable``." msgstr "" #: ../../c-api/init.rst:730 msgid "" "Return the default module search path; this is computed from the program " "name (set by :c:member:`PyConfig.program_name`) and some environment " "variables. The returned string consists of a series of directory names " "separated by a platform dependent delimiter character. The delimiter " "character is ``':'`` on Unix and macOS, ``';'`` on Windows. The returned " "string points into static storage; the caller should not modify its value. " "The list :data:`sys.path` is initialized with this value on interpreter " "startup; it can be (and usually is) modified later to change the search path" " for loading modules." msgstr "" #: ../../c-api/init.rst:748 msgid "" "Use :c:func:`PyConfig_Get(\"module_search_paths\") ` " "(:data:`sys.path`) instead." msgstr "" #: ../../c-api/init.rst:754 msgid "" "Return the version of this Python interpreter. This is a string that looks " "something like ::" msgstr "" #: ../../c-api/init.rst:757 msgid "\"3.0a5+ (py3k:63103M, May 12 2008, 00:53:55) \\n[GCC 4.2.3]\"" msgstr "" #: ../../c-api/init.rst:761 msgid "" "The first word (up to the first space character) is the current Python " "version; the first characters are the major and minor version separated by a" " period. The returned string points into static storage; the caller should " "not modify its value. The value is available to Python code as " ":data:`sys.version`." msgstr "" #: ../../c-api/init.rst:766 msgid "See also the :c:var:`Py_Version` constant." msgstr "" #: ../../c-api/init.rst:773 msgid "" "Return the platform identifier for the current platform. On Unix, this is " "formed from the \"official\" name of the operating system, converted to " "lower case, followed by the major revision number; e.g., for Solaris 2.x, " "which is also known as SunOS 5.x, the value is ``'sunos5'``. On macOS, it " "is ``'darwin'``. On Windows, it is ``'win'``. The returned string points " "into static storage; the caller should not modify its value. The value is " "available to Python code as ``sys.platform``." msgstr "" #: ../../c-api/init.rst:784 msgid "" "Return the official copyright string for the current Python version, for " "example" msgstr "" #: ../../c-api/init.rst:786 msgid "``'Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam'``" msgstr "" #: ../../c-api/init.rst:790 msgid "" "The returned string points into static storage; the caller should not modify" " its value. The value is available to Python code as ``sys.copyright``." msgstr "" #: ../../c-api/init.rst:796 msgid "" "Return an indication of the compiler used to build the current Python " "version, in square brackets, for example::" msgstr "" #: ../../c-api/init.rst:799 msgid "\"[GCC 2.7.2.2]\"" msgstr "" #: ../../c-api/init.rst:803 ../../c-api/init.rst:817 msgid "" "The returned string points into static storage; the caller should not modify" " its value. The value is available to Python code as part of the variable " "``sys.version``." msgstr "" #: ../../c-api/init.rst:810 msgid "" "Return information about the sequence number and build date and time of the" " current Python interpreter instance, for example ::" msgstr "" #: ../../c-api/init.rst:813 msgid "\"#67, Aug 1 1997, 22:34:28\"" msgstr "" #: ../../c-api/init.rst:829 msgid "" "This API is kept for backward compatibility: setting " ":c:member:`PyConfig.argv`, :c:member:`PyConfig.parse_argv` and " ":c:member:`PyConfig.safe_path` should be used instead, see :ref:`Python " "Initialization Configuration `." msgstr "" #: ../../c-api/init.rst:834 msgid "" "Set :data:`sys.argv` based on *argc* and *argv*. These parameters are " "similar to those passed to the program's :c:func:`main` function with the " "difference that the first entry should refer to the script file to be " "executed rather than the executable hosting the Python interpreter. If " "there isn't a script that will be run, the first entry in *argv* can be an " "empty string. If this function fails to initialize :data:`sys.argv`, a " "fatal condition is signalled using :c:func:`Py_FatalError`." msgstr "" #: ../../c-api/init.rst:842 msgid "" "If *updatepath* is zero, this is all the function does. If *updatepath* is " "non-zero, the function also modifies :data:`sys.path` according to the " "following algorithm:" msgstr "" #: ../../c-api/init.rst:846 msgid "" "If the name of an existing script is passed in ``argv[0]``, the absolute " "path of the directory where the script is located is prepended to " ":data:`sys.path`." msgstr "" #: ../../c-api/init.rst:849 msgid "" "Otherwise (that is, if *argc* is ``0`` or ``argv[0]`` doesn't point to an " "existing file name), an empty string is prepended to :data:`sys.path`, which" " is the same as prepending the current working directory (``\".\"``)." msgstr "" #: ../../c-api/init.rst:857 ../../c-api/init.rst:893 msgid "" "See also :c:member:`PyConfig.orig_argv` and :c:member:`PyConfig.argv` " "members of the :ref:`Python Initialization Configuration `." msgstr "" #: ../../c-api/init.rst:861 msgid "" "It is recommended that applications embedding the Python interpreter for " "purposes other than executing a single script pass ``0`` as *updatepath*, " "and update :data:`sys.path` themselves if desired. See :cve:`2008-5983`." msgstr "" #: ../../c-api/init.rst:866 msgid "" "On versions before 3.1.3, you can achieve the same effect by manually " "popping the first :data:`sys.path` element after having called " ":c:func:`PySys_SetArgv`, for example using::" msgstr "" #: ../../c-api/init.rst:870 msgid "PyRun_SimpleString(\"import sys; sys.path.pop(0)\\n\");" msgstr "" #: ../../c-api/init.rst:882 msgid "" "This API is kept for backward compatibility: setting " ":c:member:`PyConfig.argv` and :c:member:`PyConfig.parse_argv` should be used" " instead, see :ref:`Python Initialization Configuration `." msgstr "" #: ../../c-api/init.rst:886 msgid "" "This function works like :c:func:`PySys_SetArgvEx` with *updatepath* set to " "``1`` unless the :program:`python` interpreter was started with the " ":option:`-I`." msgstr "" #: ../../c-api/init.rst:896 msgid "The *updatepath* value depends on :option:`-I`." msgstr "" #: ../../c-api/init.rst:903 msgid "" "This API is kept for backward compatibility: setting " ":c:member:`PyConfig.home` should be used instead, see :ref:`Python " "Initialization Configuration `." msgstr "" #: ../../c-api/init.rst:907 msgid "" "Set the default \"home\" directory, that is, the location of the standard " "Python libraries. See :envvar:`PYTHONHOME` for the meaning of the argument " "string." msgstr "" #: ../../c-api/init.rst:911 msgid "" "The argument should point to a zero-terminated character string in static " "storage whose contents will not change for the duration of the program's " "execution. No code in the Python interpreter will change the contents of " "this storage." msgstr "" #: ../../c-api/init.rst:924 msgid "" "Return the default \"home\", that is, the value set by " ":c:member:`PyConfig.home`, or the value of the :envvar:`PYTHONHOME` " "environment variable if it is set." msgstr "" #: ../../c-api/init.rst:934 msgid "" "Use :c:func:`PyConfig_Get(\"home\") ` or the " ":envvar:`PYTHONHOME` environment variable instead." msgstr "" #: ../../c-api/init.rst:942 msgid "Thread State and the Global Interpreter Lock" msgstr "" #: ../../c-api/init.rst:949 msgid "" "Unless on a :term:`free-threaded ` build of :term:`CPython`," " the Python interpreter is not fully thread-safe. In order to support " "multi-threaded Python programs, there's a global lock, called the " ":term:`global interpreter lock` or :term:`GIL`, that must be held by the " "current thread before it can safely access Python objects. Without the lock," " even the simplest operations could cause problems in a multi-threaded " "program: for example, when two threads simultaneously increment the " "reference count of the same object, the reference count could end up being " "incremented only once instead of twice." msgstr "" #: ../../c-api/init.rst:960 msgid "" "Therefore, the rule exists that only the thread that has acquired the " ":term:`GIL` may operate on Python objects or call Python/C API functions. In" " order to emulate concurrency of execution, the interpreter regularly tries " "to switch threads (see :func:`sys.setswitchinterval`). The lock is also " "released around potentially blocking I/O operations like reading or writing " "a file, so that other Python threads can run in the meantime." msgstr "" #: ../../c-api/init.rst:970 msgid "" "The Python interpreter keeps some thread-specific bookkeeping information " "inside a data structure called :c:type:`PyThreadState`, known as a " ":term:`thread state`. Each OS thread has a thread-local pointer to a " ":c:type:`PyThreadState`; a thread state referenced by this pointer is " "considered to be :term:`attached `." msgstr "" #: ../../c-api/init.rst:975 msgid "" "A thread can only have one :term:`attached thread state` at a time. An " "attached thread state is typically analogous with holding the :term:`GIL`, " "except on :term:`free-threaded ` builds. On builds with the" " :term:`GIL` enabled, :term:`attaching ` a thread " "state will block until the :term:`GIL` can be acquired. However, even on " "builds with the :term:`GIL` disabled, it is still required to have an " "attached thread state to call most of the C API." msgstr "" #: ../../c-api/init.rst:982 msgid "" "In general, there will always be an :term:`attached thread state` when using" " Python's C API. Only in some specific cases (such as in a " ":c:macro:`Py_BEGIN_ALLOW_THREADS` block) will the thread not have an " "attached thread state. If uncertain, check if " ":c:func:`PyThreadState_GetUnchecked` returns ``NULL``." msgstr "" #: ../../c-api/init.rst:988 msgid "Detaching the thread state from extension code" msgstr "" #: ../../c-api/init.rst:990 msgid "" "Most extension code manipulating the :term:`thread state` has the following " "simple structure::" msgstr "" #: ../../c-api/init.rst:993 msgid "" "Save the thread state in a local variable.\n" "... Do some blocking I/O operation ...\n" "Restore the thread state from the local variable." msgstr "" #: ../../c-api/init.rst:997 msgid "This is so common that a pair of macros exists to simplify it::" msgstr "" #: ../../c-api/init.rst:999 msgid "" "Py_BEGIN_ALLOW_THREADS\n" "... Do some blocking I/O operation ...\n" "Py_END_ALLOW_THREADS" msgstr "" #: ../../c-api/init.rst:1007 msgid "" "The :c:macro:`Py_BEGIN_ALLOW_THREADS` macro opens a new block and declares a" " hidden local variable; the :c:macro:`Py_END_ALLOW_THREADS` macro closes the" " block." msgstr "" #: ../../c-api/init.rst:1011 msgid "The block above expands to the following code::" msgstr "" #: ../../c-api/init.rst:1013 msgid "" "PyThreadState *_save;\n" "\n" "_save = PyEval_SaveThread();\n" "... Do some blocking I/O operation ...\n" "PyEval_RestoreThread(_save);" msgstr "" #: ../../c-api/init.rst:1023 msgid "Here is how these functions work:" msgstr "" #: ../../c-api/init.rst:1025 msgid "" "The :term:`attached thread state` holds the :term:`GIL` for the entire " "interpreter. When detaching the :term:`attached thread state`, the " ":term:`GIL` is released, allowing other threads to attach a thread state to " "their own thread, thus getting the :term:`GIL` and can start executing. The " "pointer to the prior :term:`attached thread state` is stored as a local " "variable. Upon reaching :c:macro:`Py_END_ALLOW_THREADS`, the thread state " "that was previously :term:`attached ` is passed to " ":c:func:`PyEval_RestoreThread`. This function will block until another " "releases its :term:`thread state `, thus allowing the" " old :term:`thread state ` to get re-attached and the" " C API can be called again." msgstr "" #: ../../c-api/init.rst:1035 msgid "" "For :term:`free-threaded ` builds, the :term:`GIL` is " "normally out of the question, but detaching the :term:`thread state " "` is still required for blocking I/O and long " "operations. The difference is that threads don't have to wait for the " ":term:`GIL` to be released to attach their thread state, allowing true " "multi-core parallelism." msgstr "" #: ../../c-api/init.rst:1041 msgid "" "Calling system I/O functions is the most common use case for detaching the " ":term:`thread state `, but it can also be useful " "before calling long-running computations which don't need access to Python " "objects, such as compression or cryptographic functions operating over " "memory buffers. For example, the standard :mod:`zlib` and :mod:`hashlib` " "modules detach the :term:`thread state ` when " "compressing or hashing data." msgstr "" #: ../../c-api/init.rst:1052 msgid "Non-Python created threads" msgstr "" #: ../../c-api/init.rst:1054 msgid "" "When threads are created using the dedicated Python APIs (such as the " ":mod:`threading` module), a thread state is automatically associated to them" " and the code showed above is therefore correct. However, when threads are " "created from C (for example by a third-party library with its own thread " "management), they don't hold the :term:`GIL`, because they don't have an " ":term:`attached thread state`." msgstr "" #: ../../c-api/init.rst:1061 msgid "" "If you need to call Python code from these threads (often this will be part " "of a callback API provided by the aforementioned third-party library), you " "must first register these threads with the interpreter by creating an " ":term:`attached thread state` before you can start using the Python/C API. " "When you are done, you should detach the :term:`thread state `, and finally free it." msgstr "" #: ../../c-api/init.rst:1068 msgid "" "The :c:func:`PyGILState_Ensure` and :c:func:`PyGILState_Release` functions " "do all of the above automatically. The typical idiom for calling into " "Python from a C thread is::" msgstr "" #: ../../c-api/init.rst:1072 msgid "" "PyGILState_STATE gstate;\n" "gstate = PyGILState_Ensure();\n" "\n" "/* Perform Python actions here. */\n" "result = CallSomeFunction();\n" "/* evaluate result or handle exception */\n" "\n" "/* Release the thread. No Python API allowed beyond this point. */\n" "PyGILState_Release(gstate);" msgstr "" #: ../../c-api/init.rst:1082 msgid "" "Note that the ``PyGILState_*`` functions assume there is only one global " "interpreter (created automatically by :c:func:`Py_Initialize`). Python " "supports the creation of additional interpreters (using " ":c:func:`Py_NewInterpreter`), but mixing multiple interpreters and the " "``PyGILState_*`` API is unsupported." msgstr "" #: ../../c-api/init.rst:1092 msgid "Cautions about fork()" msgstr "" #: ../../c-api/init.rst:1094 msgid "" "Another important thing to note about threads is their behaviour in the face" " of the C :c:func:`fork` call. On most systems with :c:func:`fork`, after a " "process forks only the thread that issued the fork will exist. This has a " "concrete impact both on how locks must be handled and on all stored state in" " CPython's runtime." msgstr "" #: ../../c-api/init.rst:1100 msgid "" "The fact that only the \"current\" thread remains means any locks held by " "other threads will never be released. Python solves this for :func:`os.fork`" " by acquiring the locks it uses internally before the fork, and releasing " "them afterwards. In addition, it resets any :ref:`lock-objects` in the " "child. When extending or embedding Python, there is no way to inform Python " "of additional (non-Python) locks that need to be acquired before or reset " "after a fork. OS facilities such as :c:func:`!pthread_atfork` would need to " "be used to accomplish the same thing. Additionally, when extending or " "embedding Python, calling :c:func:`fork` directly rather than through " ":func:`os.fork` (and returning to or calling into Python) may result in a " "deadlock by one of Python's internal locks being held by a thread that is " "defunct after the fork. :c:func:`PyOS_AfterFork_Child` tries to reset the " "necessary locks, but is not always able to." msgstr "" #: ../../c-api/init.rst:1115 msgid "" "The fact that all other threads go away also means that CPython's runtime " "state there must be cleaned up properly, which :func:`os.fork` does. This " "means finalizing all other :c:type:`PyThreadState` objects belonging to the " "current interpreter and all other :c:type:`PyInterpreterState` objects. Due" " to this and the special nature of the :ref:`\"main\" interpreter `, :c:func:`fork` should only be called in that " "interpreter's \"main\" thread, where the CPython global runtime was " "originally initialized. The only exception is if :c:func:`exec` will be " "called immediately after." msgstr "" #: ../../c-api/init.rst:1129 msgid "Cautions regarding runtime finalization" msgstr "" #: ../../c-api/init.rst:1131 msgid "" "In the late stage of :term:`interpreter shutdown`, after attempting to wait " "for non-daemon threads to exit (though this can be interrupted by " ":class:`KeyboardInterrupt`) and running the :mod:`atexit` functions, the " "runtime is marked as *finalizing*: :c:func:`Py_IsFinalizing` and " ":func:`sys.is_finalizing` return true. At this point, only the " "*finalization thread* that initiated finalization (typically the main " "thread) is allowed to acquire the :term:`GIL`." msgstr "" #: ../../c-api/init.rst:1139 msgid "" "If any thread, other than the finalization thread, attempts to attach a " ":term:`thread state` during finalization, either explicitly or implicitly, " "the thread enters **a permanently blocked state** where it remains until the" " program exits. In most cases this is harmless, but this can result in " "deadlock if a later stage of finalization attempts to acquire a lock owned " "by the blocked thread, or otherwise waits on the blocked thread." msgstr "" #: ../../c-api/init.rst:1146 msgid "" "Gross? Yes. This prevents random crashes and/or unexpectedly skipped C++ " "finalizations further up the call stack when such threads were forcibly " "exited here in CPython 3.13 and earlier. The CPython runtime :term:`thread " "state` C APIs have never had any error reporting or handling expectations at" " :term:`thread state` attachment time that would've allowed for graceful " "exit from this situation. Changing that would require new stable C APIs and " "rewriting the majority of C code in the CPython ecosystem to use those with " "error handling." msgstr "" #: ../../c-api/init.rst:1156 msgid "High-level API" msgstr "" #: ../../c-api/init.rst:1158 msgid "" "These are the most commonly used types and functions when writing C " "extension code, or when embedding the Python interpreter:" msgstr "" #: ../../c-api/init.rst:1163 msgid "" "This data structure represents the state shared by a number of cooperating " "threads. Threads belonging to the same interpreter share their module " "administration and a few other internal items. There are no public members " "in this structure." msgstr "" #: ../../c-api/init.rst:1168 msgid "" "Threads belonging to different interpreters initially share nothing, except " "process state like available memory, open file descriptors and such. The " "global interpreter lock is also shared by all threads, regardless of to " "which interpreter they belong." msgstr "" #: ../../c-api/init.rst:1176 msgid "" "This data structure represents the state of a single thread. The only " "public data member is:" msgstr "" #: ../../c-api/init.rst:1181 msgid "This thread's interpreter state." msgstr "" #: ../../c-api/init.rst:1192 msgid "Deprecated function which does nothing." msgstr "" #: ../../c-api/init.rst:1194 msgid "" "In Python 3.6 and older, this function created the GIL if it didn't exist." msgstr "" #: ../../c-api/init.rst:1196 msgid "The function now does nothing." msgstr "" #: ../../c-api/init.rst:1199 msgid "" "This function is now called by :c:func:`Py_Initialize()`, so you don't have " "to call it yourself anymore." msgstr "" #: ../../c-api/init.rst:1203 msgid "" "This function cannot be called before :c:func:`Py_Initialize()` anymore." msgstr "" #: ../../c-api/init.rst:1213 msgid "" "Detach the :term:`attached thread state` and return it. The thread will have" " no :term:`thread state` upon returning." msgstr "" #: ../../c-api/init.rst:1219 msgid "" "Set the :term:`attached thread state` to *tstate*. The passed :term:`thread " "state` **should not** be :term:`attached `, otherwise" " deadlock ensues. *tstate* will be attached upon returning." msgstr "" #: ../../c-api/init.rst:1224 ../../c-api/init.rst:1291 #: ../../c-api/init.rst:1582 msgid "" "Calling this function from a thread when the runtime is finalizing will hang" " the thread until the program exits, even if the thread was not created by " "Python. Refer to :ref:`cautions-regarding-runtime-finalization` for more " "details." msgstr "" #: ../../c-api/init.rst:1229 ../../c-api/init.rst:1296 #: ../../c-api/init.rst:1592 msgid "" "Hangs the current thread, rather than terminating it, if called while the " "interpreter is finalizing." msgstr "" #: ../../c-api/init.rst:1235 msgid "" "Return the :term:`attached thread state`. If the thread has no attached " "thread state, (such as when inside of :c:macro:`Py_BEGIN_ALLOW_THREADS` " "block), then this issues a fatal error (so that the caller needn't check for" " ``NULL``)." msgstr "" #: ../../c-api/init.rst:1240 msgid "See also :c:func:`PyThreadState_GetUnchecked`." msgstr "" #: ../../c-api/init.rst:1244 msgid "" "Similar to :c:func:`PyThreadState_Get`, but don't kill the process with a " "fatal error if it is NULL. The caller is responsible to check if the result " "is NULL." msgstr "" #: ../../c-api/init.rst:1248 msgid "" "In Python 3.5 to 3.12, the function was private and known as " "``_PyThreadState_UncheckedGet()``." msgstr "" #: ../../c-api/init.rst:1255 msgid "" "Set the :term:`attached thread state` to *tstate*, and return the " ":term:`thread state` that was attached prior to calling." msgstr "" #: ../../c-api/init.rst:1258 msgid "" "This function is safe to call without an :term:`attached thread state`; it " "will simply return ``NULL`` indicating that there was no prior thread state." msgstr "" #: ../../c-api/init.rst:1265 msgid "" "The following functions use thread-local storage, and are not compatible " "with sub-interpreters:" msgstr "" #: ../../c-api/init.rst:1270 msgid "" "Ensure that the current thread is ready to call the Python C API regardless " "of the current state of Python, or of the :term:`attached thread state`. " "This may be called as many times as desired by a thread as long as each call" " is matched with a call to :c:func:`PyGILState_Release`. In general, other " "thread-related APIs may be used between :c:func:`PyGILState_Ensure` and " ":c:func:`PyGILState_Release` calls as long as the thread state is restored " "to its previous state before the Release(). For example, normal usage of " "the :c:macro:`Py_BEGIN_ALLOW_THREADS` and :c:macro:`Py_END_ALLOW_THREADS` " "macros is acceptable." msgstr "" #: ../../c-api/init.rst:1280 msgid "" "The return value is an opaque \"handle\" to the :term:`attached thread " "state` when :c:func:`PyGILState_Ensure` was called, and must be passed to " ":c:func:`PyGILState_Release` to ensure Python is left in the same state. " "Even though recursive calls are allowed, these handles *cannot* be shared - " "each unique call to :c:func:`PyGILState_Ensure` must save the handle for its" " call to :c:func:`PyGILState_Release`." msgstr "" #: ../../c-api/init.rst:1287 msgid "" "When the function returns, there will be an :term:`attached thread state` " "and the thread will be able to call arbitrary Python code. Failure is a " "fatal error." msgstr "" #: ../../c-api/init.rst:1302 msgid "" "Release any resources previously acquired. After this call, Python's state " "will be the same as it was prior to the corresponding " ":c:func:`PyGILState_Ensure` call (but generally this state will be unknown " "to the caller, hence the use of the GILState API)." msgstr "" #: ../../c-api/init.rst:1307 msgid "" "Every call to :c:func:`PyGILState_Ensure` must be matched by a call to " ":c:func:`PyGILState_Release` on the same thread." msgstr "" #: ../../c-api/init.rst:1313 msgid "" "Get the :term:`attached thread state` for this thread. May return ``NULL`` " "if no GILState API has been used on the current thread. Note that the main " "thread always has such a thread-state, even if no auto-thread-state call has" " been made on the main thread. This is mainly a helper/diagnostic function." msgstr "" #: ../../c-api/init.rst:1323 msgid "" "Return ``1`` if the current thread is holding the :term:`GIL` and ``0`` " "otherwise. This function can be called from any thread at any time. Only if " "it has had its Python thread state initialized and currently is holding the " ":term:`GIL` will it return ``1``. This is mainly a helper/diagnostic " "function. It can be useful for example in callback contexts or memory " "allocation functions when knowing that the :term:`GIL` is locked can allow " "the caller to perform sensitive actions or otherwise behave differently." msgstr "" #: ../../c-api/init.rst:1335 msgid "" "The following macros are normally used without a trailing semicolon; look " "for example usage in the Python source distribution." msgstr "" #: ../../c-api/init.rst:1341 msgid "" "This macro expands to ``{ PyThreadState *_save; _save = " "PyEval_SaveThread();``. Note that it contains an opening brace; it must be " "matched with a following :c:macro:`Py_END_ALLOW_THREADS` macro. See above " "for further discussion of this macro." msgstr "" #: ../../c-api/init.rst:1349 msgid "" "This macro expands to ``PyEval_RestoreThread(_save); }``. Note that it " "contains a closing brace; it must be matched with an earlier " ":c:macro:`Py_BEGIN_ALLOW_THREADS` macro. See above for further discussion " "of this macro." msgstr "" #: ../../c-api/init.rst:1357 msgid "" "This macro expands to ``PyEval_RestoreThread(_save);``: it is equivalent to " ":c:macro:`Py_END_ALLOW_THREADS` without the closing brace." msgstr "" #: ../../c-api/init.rst:1363 msgid "" "This macro expands to ``_save = PyEval_SaveThread();``: it is equivalent to " ":c:macro:`Py_BEGIN_ALLOW_THREADS` without the opening brace and variable " "declaration." msgstr "" #: ../../c-api/init.rst:1369 msgid "Low-level API" msgstr "" #: ../../c-api/init.rst:1371 msgid "" "All of the following functions must be called after :c:func:`Py_Initialize`." msgstr "" #: ../../c-api/init.rst:1373 msgid "" ":c:func:`Py_Initialize()` now initializes the :term:`GIL` and sets an " ":term:`attached thread state`." msgstr "" #: ../../c-api/init.rst:1380 msgid "" "Create a new interpreter state object. An :term:`attached thread state` is " "not needed, but may optionally exist if it is necessary to serialize calls " "to this function." msgstr "" #: ../../c-api/init.rst:1384 msgid "" "Raises an :ref:`auditing event ` " "``cpython.PyInterpreterState_New`` with no arguments." msgstr "" #: ../../c-api/init.rst:1389 msgid "" "Reset all information in an interpreter state object. There must be an " ":term:`attached thread state` for the the interpreter." msgstr "" #: ../../c-api/init.rst:1392 msgid "" "Raises an :ref:`auditing event ` " "``cpython.PyInterpreterState_Clear`` with no arguments." msgstr "" #: ../../c-api/init.rst:1397 msgid "" "Destroy an interpreter state object. There **should not** be an " ":term:`attached thread state` for the target interpreter. The interpreter " "state must have been reset with a previous call to " ":c:func:`PyInterpreterState_Clear`." msgstr "" #: ../../c-api/init.rst:1404 msgid "" "Create a new thread state object belonging to the given interpreter object. " "An :term:`attached thread state` is not needed." msgstr "" #: ../../c-api/init.rst:1409 msgid "" "Reset all information in a :term:`thread state` object. *tstate* must be " ":term:`attached `" msgstr "" #: ../../c-api/init.rst:1412 msgid "" "This function now calls the :c:member:`PyThreadState.on_delete` callback. " "Previously, that happened in :c:func:`PyThreadState_Delete`." msgstr "" #: ../../c-api/init.rst:1416 msgid "The :c:member:`PyThreadState.on_delete` callback was removed." msgstr "" #: ../../c-api/init.rst:1422 msgid "" "Destroy a :term:`thread state` object. *tstate* should not be " ":term:`attached ` to any thread. *tstate* must have " "been reset with a previous call to :c:func:`PyThreadState_Clear`." msgstr "" #: ../../c-api/init.rst:1430 msgid "" "Detach the :term:`attached thread state` (which must have been reset with a " "previous call to :c:func:`PyThreadState_Clear`) and then destroy it." msgstr "" #: ../../c-api/init.rst:1433 msgid "" "No :term:`thread state` will be :term:`attached ` " "upon returning." msgstr "" #: ../../c-api/init.rst:1438 msgid "Get the current frame of the Python thread state *tstate*." msgstr "" #: ../../c-api/init.rst:1440 msgid "" "Return a :term:`strong reference`. Return ``NULL`` if no frame is currently " "executing." msgstr "" #: ../../c-api/init.rst:1443 msgid "See also :c:func:`PyEval_GetFrame`." msgstr "" #: ../../c-api/init.rst:1445 ../../c-api/init.rst:1454 #: ../../c-api/init.rst:1463 msgid "" "*tstate* must not be ``NULL``, and must be :term:`attached `." msgstr "" #: ../../c-api/init.rst:1452 msgid "" "Get the unique :term:`thread state` identifier of the Python thread state " "*tstate*." msgstr "" #: ../../c-api/init.rst:1461 msgid "Get the interpreter of the Python thread state *tstate*." msgstr "" #: ../../c-api/init.rst:1470 msgid "Suspend tracing and profiling in the Python thread state *tstate*." msgstr "" #: ../../c-api/init.rst:1472 msgid "Resume them using the :c:func:`PyThreadState_LeaveTracing` function." msgstr "" #: ../../c-api/init.rst:1479 msgid "" "Resume tracing and profiling in the Python thread state *tstate* suspended " "by the :c:func:`PyThreadState_EnterTracing` function." msgstr "" #: ../../c-api/init.rst:1482 msgid "" "See also :c:func:`PyEval_SetTrace` and :c:func:`PyEval_SetProfile` " "functions." msgstr "" #: ../../c-api/init.rst:1490 msgid "Get the current interpreter." msgstr "" #: ../../c-api/init.rst:1492 msgid "" "Issue a fatal error if there no :term:`attached thread state`. It cannot " "return NULL." msgstr "" #: ../../c-api/init.rst:1500 msgid "" "Return the interpreter's unique ID. If there was any error in doing so then" " ``-1`` is returned and an error is set." msgstr "" #: ../../c-api/init.rst:1503 ../../c-api/init.rst:2090 #: ../../c-api/init.rst:2097 ../../c-api/init.rst:2116 #: ../../c-api/init.rst:2123 msgid "The caller must have an :term:`attached thread state`." msgstr "" #: ../../c-api/init.rst:1510 msgid "" "Return a dictionary in which interpreter-specific data may be stored. If " "this function returns ``NULL`` then no exception has been raised and the " "caller should assume no interpreter-specific dict is available." msgstr "" #: ../../c-api/init.rst:1514 msgid "" "This is not a replacement for :c:func:`PyModule_GetState()`, which " "extensions should use to store interpreter-specific state information." msgstr "" #: ../../c-api/init.rst:1522 msgid "Type of a frame evaluation function." msgstr "" #: ../../c-api/init.rst:1524 msgid "" "The *throwflag* parameter is used by the ``throw()`` method of generators: " "if non-zero, handle the current exception." msgstr "" #: ../../c-api/init.rst:1527 msgid "The function now takes a *tstate* parameter." msgstr "" #: ../../c-api/init.rst:1530 msgid "" "The *frame* parameter changed from ``PyFrameObject*`` to " "``_PyInterpreterFrame*``." msgstr "" #: ../../c-api/init.rst:1535 msgid "Get the frame evaluation function." msgstr "" #: ../../c-api/init.rst:1537 ../../c-api/init.rst:1545 msgid "See the :pep:`523` \"Adding a frame evaluation API to CPython\"." msgstr "" #: ../../c-api/init.rst:1543 msgid "Set the frame evaluation function." msgstr "" #: ../../c-api/init.rst:1552 msgid "" "Return a dictionary in which extensions can store thread-specific state " "information. Each extension should use a unique key to use to store state " "in the dictionary. It is okay to call this function when no :term:`thread " "state` is :term:`attached `. If this function returns" " ``NULL``, no exception has been raised and the caller should assume no " "thread state is attached." msgstr "" #: ../../c-api/init.rst:1562 msgid "" "Asynchronously raise an exception in a thread. The *id* argument is the " "thread id of the target thread; *exc* is the exception object to be raised. " "This function does not steal any references to *exc*. To prevent naive " "misuse, you must write your own C extension to call this. Must be called " "with an :term:`attached thread state`. Returns the number of thread states " "modified; this is normally one, but will be zero if the thread id isn't " "found. If *exc* is ``NULL``, the pending exception (if any) for the thread " "is cleared. This raises no exceptions." msgstr "" #: ../../c-api/init.rst:1570 msgid "" "The type of the *id* parameter changed from :c:expr:`long` to " ":c:expr:`unsigned long`." msgstr "" #: ../../c-api/init.rst:1576 msgid "" ":term:`Attach ` *tstate* to the current thread, which" " must not be ``NULL`` or already :term:`attached `." msgstr "" #: ../../c-api/init.rst:1579 msgid "" "The calling thread must not already have an :term:`attached thread state`." msgstr "" #: ../../c-api/init.rst:1587 msgid "" "Updated to be consistent with :c:func:`PyEval_RestoreThread`, " ":c:func:`Py_END_ALLOW_THREADS`, and :c:func:`PyGILState_Ensure`, and " "terminate the current thread if called while the interpreter is finalizing." msgstr "" #: ../../c-api/init.rst:1596 msgid "" ":c:func:`PyEval_RestoreThread` is a higher-level function which is always " "available (even when threads have not been initialized)." msgstr "" #: ../../c-api/init.rst:1602 msgid "" "Detach the :term:`attached thread state`. The *tstate* argument, which must " "not be ``NULL``, is only used to check that it represents the " ":term:`attached thread state` --- if it isn't, a fatal error is reported." msgstr "" #: ../../c-api/init.rst:1607 msgid "" ":c:func:`PyEval_SaveThread` is a higher-level function which is always " "available (even when threads have not been initialized)." msgstr "" #: ../../c-api/init.rst:1614 msgid "Sub-interpreter support" msgstr "" #: ../../c-api/init.rst:1616 msgid "" "While in most uses, you will only embed a single Python interpreter, there " "are cases where you need to create several independent interpreters in the " "same process and perhaps even in the same thread. Sub-interpreters allow you" " to do that." msgstr "" #: ../../c-api/init.rst:1621 msgid "" "The \"main\" interpreter is the first one created when the runtime " "initializes. It is usually the only Python interpreter in a process. Unlike" " sub-interpreters, the main interpreter has unique process-global " "responsibilities like signal handling. It is also responsible for execution" " during runtime initialization and is usually the active interpreter during " "runtime finalization. The :c:func:`PyInterpreterState_Main` function " "returns a pointer to its state." msgstr "" #: ../../c-api/init.rst:1628 msgid "" "You can switch between sub-interpreters using the " ":c:func:`PyThreadState_Swap` function. You can create and destroy them using" " the following functions:" msgstr "" #: ../../c-api/init.rst:1634 msgid "" "Structure containing most parameters to configure a sub-interpreter. Its " "values are used only in :c:func:`Py_NewInterpreterFromConfig` and never " "modified by the runtime." msgstr "" #: ../../c-api/init.rst:1640 msgid "Structure fields:" msgstr "" #: ../../c-api/init.rst:1644 msgid "" "If this is ``0`` then the sub-interpreter will use its own \"object\" " "allocator state. Otherwise it will use (share) the main interpreter's." msgstr "" #: ../../c-api/init.rst:1648 msgid "" "If this is ``0`` then " ":c:member:`~PyInterpreterConfig.check_multi_interp_extensions` must be ``1``" " (non-zero). If this is ``1`` then :c:member:`~PyInterpreterConfig.gil` must" " not be :c:macro:`PyInterpreterConfig_OWN_GIL`." msgstr "" #: ../../c-api/init.rst:1656 msgid "" "If this is ``0`` then the runtime will not support forking the process in " "any thread where the sub-interpreter is currently active. Otherwise fork is " "unrestricted." msgstr "" #: ../../c-api/init.rst:1660 msgid "" "Note that the :mod:`subprocess` module still works when fork is disallowed." msgstr "" #: ../../c-api/init.rst:1665 msgid "" "If this is ``0`` then the runtime will not support replacing the current " "process via exec (e.g. :func:`os.execv`) in any thread where the sub-" "interpreter is currently active. Otherwise exec is unrestricted." msgstr "" #: ../../c-api/init.rst:1670 msgid "" "Note that the :mod:`subprocess` module still works when exec is disallowed." msgstr "" #: ../../c-api/init.rst:1675 msgid "" "If this is ``0`` then the sub-interpreter's :mod:`threading` module won't " "create threads. Otherwise threads are allowed." msgstr "" #: ../../c-api/init.rst:1681 msgid "" "If this is ``0`` then the sub-interpreter's :mod:`threading` module won't " "create daemon threads. Otherwise daemon threads are allowed (as long as " ":c:member:`~PyInterpreterConfig.allow_threads` is non-zero)." msgstr "" #: ../../c-api/init.rst:1688 msgid "" "If this is ``0`` then all extension modules may be imported, including " "legacy (single-phase init) modules, in any thread where the sub-interpreter " "is currently active. Otherwise only multi-phase init extension modules (see " ":pep:`489`) may be imported. (Also see " ":c:macro:`Py_mod_multiple_interpreters`.)" msgstr "" #: ../../c-api/init.rst:1695 msgid "" "This must be ``1`` (non-zero) if " ":c:member:`~PyInterpreterConfig.use_main_obmalloc` is ``0``." msgstr "" #: ../../c-api/init.rst:1700 msgid "" "This determines the operation of the GIL for the sub-interpreter. It may be " "one of the following:" msgstr "" #: ../../c-api/init.rst:1707 msgid "Use the default selection (:c:macro:`PyInterpreterConfig_SHARED_GIL`)." msgstr "" #: ../../c-api/init.rst:1711 msgid "Use (share) the main interpreter's GIL." msgstr "" #: ../../c-api/init.rst:1715 msgid "Use the sub-interpreter's own GIL." msgstr "" #: ../../c-api/init.rst:1717 msgid "" "If this is :c:macro:`PyInterpreterConfig_OWN_GIL` then " ":c:member:`PyInterpreterConfig.use_main_obmalloc` must be ``0``." msgstr "" #: ../../c-api/init.rst:1731 msgid "" "Create a new sub-interpreter. This is an (almost) totally separate " "environment for the execution of Python code. In particular, the new " "interpreter has separate, independent versions of all imported modules, " "including the fundamental modules :mod:`builtins`, :mod:`__main__` and " ":mod:`sys`. The table of loaded modules (``sys.modules``) and the module " "search path (``sys.path``) are also separate. The new environment has no " "``sys.argv`` variable. It has new standard I/O stream file objects " "``sys.stdin``, ``sys.stdout`` and ``sys.stderr`` (however these refer to the" " same underlying file descriptors)." msgstr "" #: ../../c-api/init.rst:1741 msgid "" "The given *config* controls the options with which the interpreter is " "initialized." msgstr "" #: ../../c-api/init.rst:1744 msgid "" "Upon success, *tstate_p* will be set to the first :term:`thread state` " "created in the new sub-interpreter. This thread state is :term:`attached " "`. Note that no actual thread is created; see the " "discussion of thread states below. If creation of the new interpreter is " "unsuccessful, *tstate_p* is set to ``NULL``; no exception is set since the " "exception state is stored in the :term:`attached thread state`, which might " "not exist." msgstr "" #: ../../c-api/init.rst:1753 msgid "" "Like all other Python/C API functions, an :term:`attached thread state` must" " be present before calling this function, but it might be detached upon " "returning. On success, the returned thread state will be :term:`attached " "`. If the sub-interpreter is created with its own " ":term:`GIL` then the :term:`attached thread state` of the calling " "interpreter will be detached. When the function returns, the new " "interpreter's :term:`thread state` will be :term:`attached ` to the current thread and the previous interpreter's :term:`attached" " thread state` will remain detached." msgstr "" #: ../../c-api/init.rst:1764 msgid "" "Sub-interpreters are most effective when isolated from each other, with " "certain functionality restricted::" msgstr "" #: ../../c-api/init.rst:1767 msgid "" "PyInterpreterConfig config = {\n" " .use_main_obmalloc = 0,\n" " .allow_fork = 0,\n" " .allow_exec = 0,\n" " .allow_threads = 1,\n" " .allow_daemon_threads = 0,\n" " .check_multi_interp_extensions = 1,\n" " .gil = PyInterpreterConfig_OWN_GIL,\n" "};\n" "PyThreadState *tstate = NULL;\n" "PyStatus status = Py_NewInterpreterFromConfig(&tstate, &config);\n" "if (PyStatus_Exception(status)) {\n" " Py_ExitStatusException(status);\n" "}" msgstr "" #: ../../c-api/init.rst:1782 msgid "" "Note that the config is used only briefly and does not get modified. During " "initialization the config's values are converted into various " ":c:type:`PyInterpreterState` values. A read-only copy of the config may be " "stored internally on the :c:type:`PyInterpreterState`." msgstr "" #: ../../c-api/init.rst:1791 msgid "Extension modules are shared between (sub-)interpreters as follows:" msgstr "" #: ../../c-api/init.rst:1793 msgid "" "For modules using multi-phase initialization, e.g. " ":c:func:`PyModule_FromDefAndSpec`, a separate module object is created and " "initialized for each interpreter. Only C-level static and global variables " "are shared between these module objects." msgstr "" #: ../../c-api/init.rst:1799 msgid "" "For modules using single-phase initialization, e.g. " ":c:func:`PyModule_Create`, the first time a particular extension is " "imported, it is initialized normally, and a (shallow) copy of its module's " "dictionary is squirreled away. When the same extension is imported by " "another (sub-)interpreter, a new module is initialized and filled with the " "contents of this copy; the extension's ``init`` function is not called. " "Objects in the module's dictionary thus end up shared across " "(sub-)interpreters, which might cause unwanted behavior (see `Bugs and " "caveats`_ below)." msgstr "" #: ../../c-api/init.rst:1810 msgid "" "Note that this is different from what happens when an extension is imported " "after the interpreter has been completely re-initialized by calling " ":c:func:`Py_FinalizeEx` and :c:func:`Py_Initialize`; in that case, the " "extension's ``initmodule`` function *is* called again. As with multi-phase " "initialization, this means that only C-level static and global variables are" " shared between these modules." msgstr "" #: ../../c-api/init.rst:1830 msgid "" "Create a new sub-interpreter. This is essentially just a wrapper around " ":c:func:`Py_NewInterpreterFromConfig` with a config that preserves the " "existing behavior. The result is an unisolated sub-interpreter that shares " "the main interpreter's GIL, allows fork/exec, allows daemon threads, and " "allows single-phase init modules." msgstr "" #: ../../c-api/init.rst:1842 msgid "" "Destroy the (sub-)interpreter represented by the given :term:`thread state`." " The given thread state must be :term:`attached `. " "When the call returns, there will be no :term:`attached thread state`. All " "thread states associated with this interpreter are destroyed." msgstr "" #: ../../c-api/init.rst:1847 msgid "" ":c:func:`Py_FinalizeEx` will destroy all sub-interpreters that haven't been " "explicitly destroyed at that point." msgstr "" #: ../../c-api/init.rst:1852 msgid "A Per-Interpreter GIL" msgstr "" #: ../../c-api/init.rst:1854 msgid "" "Using :c:func:`Py_NewInterpreterFromConfig` you can create a sub-interpreter" " that is completely isolated from other interpreters, including having its " "own GIL. The most important benefit of this isolation is that such an " "interpreter can execute Python code without being blocked by other " "interpreters or blocking any others. Thus a single Python process can truly" " take advantage of multiple CPU cores when running Python code. The " "isolation also encourages a different approach to concurrency than that of " "just using threads. (See :pep:`554`.)" msgstr "" #: ../../c-api/init.rst:1864 msgid "" "Using an isolated interpreter requires vigilance in preserving that " "isolation. That especially means not sharing any objects or mutable state " "without guarantees about thread-safety. Even objects that are otherwise " "immutable (e.g. ``None``, ``(1, 5)``) can't normally be shared because of " "the refcount. One simple but less-efficient approach around this is to use " "a global lock around all use of some state (or object). Alternately, " "effectively immutable objects (like integers or strings) can be made safe in" " spite of their refcounts by making them :term:`immortal`. In fact, this has" " been done for the builtin singletons, small integers, and a number of other" " builtin objects." msgstr "" #: ../../c-api/init.rst:1875 msgid "" "If you preserve isolation then you will have access to proper multi-core " "computing without the complications that come with free-threading. Failure " "to preserve isolation will expose you to the full consequences of free-" "threading, including races and hard-to-debug crashes." msgstr "" #: ../../c-api/init.rst:1880 msgid "" "Aside from that, one of the main challenges of using multiple isolated " "interpreters is how to communicate between them safely (not break isolation)" " and efficiently. The runtime and stdlib do not provide any standard " "approach to this yet. A future stdlib module would help mitigate the effort" " of preserving isolation and expose effective tools for communicating (and " "sharing) data between interpreters." msgstr "" #: ../../c-api/init.rst:1891 msgid "Bugs and caveats" msgstr "" #: ../../c-api/init.rst:1893 msgid "" "Because sub-interpreters (and the main interpreter) are part of the same " "process, the insulation between them isn't perfect --- for example, using " "low-level file operations like :func:`os.close` they can (accidentally or " "maliciously) affect each other's open files. Because of the way extensions " "are shared between (sub-)interpreters, some extensions may not work " "properly; this is especially likely when using single-phase initialization " "or (static) global variables. It is possible to insert objects created in " "one sub-interpreter into a namespace of another (sub-)interpreter; this " "should be avoided if possible." msgstr "" #: ../../c-api/init.rst:1903 msgid "" "Special care should be taken to avoid sharing user-defined functions, " "methods, instances or classes between sub-interpreters, since import " "operations executed by such objects may affect the wrong (sub-)interpreter's" " dictionary of loaded modules. It is equally important to avoid sharing " "objects from which the above are reachable." msgstr "" #: ../../c-api/init.rst:1909 msgid "" "Also note that combining this functionality with ``PyGILState_*`` APIs is " "delicate, because these APIs assume a bijection between Python thread states" " and OS-level threads, an assumption broken by the presence of sub-" "interpreters. It is highly recommended that you don't switch sub-" "interpreters between a pair of matching :c:func:`PyGILState_Ensure` and " ":c:func:`PyGILState_Release` calls. Furthermore, extensions (such as " ":mod:`ctypes`) using these APIs to allow calling of Python code from non-" "Python created threads will probably be broken when using sub-interpreters." msgstr "" #: ../../c-api/init.rst:1920 msgid "Asynchronous Notifications" msgstr "" #: ../../c-api/init.rst:1922 msgid "" "A mechanism is provided to make asynchronous notifications to the main " "interpreter thread. These notifications take the form of a function pointer" " and a void pointer argument." msgstr "" #: ../../c-api/init.rst:1929 msgid "" "Schedule a function to be called from the main interpreter thread. On " "success, ``0`` is returned and *func* is queued for being called in the main" " thread. On failure, ``-1`` is returned without setting any exception." msgstr "" #: ../../c-api/init.rst:1933 msgid "" "When successfully queued, *func* will be *eventually* called from the main " "interpreter thread with the argument *arg*. It will be called " "asynchronously with respect to normally running Python code, but with both " "these conditions met:" msgstr "" #: ../../c-api/init.rst:1938 msgid "on a :term:`bytecode` boundary;" msgstr "" #: ../../c-api/init.rst:1939 msgid "" "with the main thread holding an :term:`attached thread state` (*func* can " "therefore use the full C API)." msgstr "" #: ../../c-api/init.rst:1942 msgid "" "*func* must return ``0`` on success, or ``-1`` on failure with an exception " "set. *func* won't be interrupted to perform another asynchronous " "notification recursively, but it can still be interrupted to switch threads " "if the :term:`thread state ` is detached." msgstr "" #: ../../c-api/init.rst:1947 msgid "" "This function doesn't need an :term:`attached thread state`. However, to " "call this function in a subinterpreter, the caller must have an " ":term:`attached thread state`. Otherwise, the function *func* can be " "scheduled to be called from the wrong interpreter." msgstr "" #: ../../c-api/init.rst:1952 msgid "" "This is a low-level function, only useful for very special cases. There is " "no guarantee that *func* will be called as quick as possible. If the main " "thread is busy executing a system call, *func* won't be called before the " "system call returns. This function is generally **not** suitable for " "calling Python code from arbitrary C threads. Instead, use the " ":ref:`PyGILState API`." msgstr "" #: ../../c-api/init.rst:1961 msgid "" "If this function is called in a subinterpreter, the function *func* is now " "scheduled to be called from the subinterpreter, rather than being called " "from the main interpreter. Each subinterpreter now has its own list of " "scheduled calls." msgstr "" #: ../../c-api/init.rst:1970 msgid "Profiling and Tracing" msgstr "" #: ../../c-api/init.rst:1975 msgid "" "The Python interpreter provides some low-level support for attaching " "profiling and execution tracing facilities. These are used for profiling, " "debugging, and coverage analysis tools." msgstr "" #: ../../c-api/init.rst:1979 msgid "" "This C interface allows the profiling or tracing code to avoid the overhead " "of calling through Python-level callable objects, making a direct C function" " call instead. The essential attributes of the facility have not changed; " "the interface allows trace functions to be installed per-thread, and the " "basic events reported to the trace function are the same as had been " "reported to the Python-level trace functions in previous versions." msgstr "" #: ../../c-api/init.rst:1989 msgid "" "The type of the trace function registered using :c:func:`PyEval_SetProfile` " "and :c:func:`PyEval_SetTrace`. The first parameter is the object passed to " "the registration function as *obj*, *frame* is the frame object to which the" " event pertains, *what* is one of the constants :c:data:`PyTrace_CALL`, " ":c:data:`PyTrace_EXCEPTION`, :c:data:`PyTrace_LINE`, " ":c:data:`PyTrace_RETURN`, :c:data:`PyTrace_C_CALL`, " ":c:data:`PyTrace_C_EXCEPTION`, :c:data:`PyTrace_C_RETURN`, or " ":c:data:`PyTrace_OPCODE`, and *arg* depends on the value of *what*:" msgstr "" #: ../../c-api/init.rst:1998 msgid "Value of *what*" msgstr "" #: ../../c-api/init.rst:1998 msgid "Meaning of *arg*" msgstr "" #: ../../c-api/init.rst:2000 msgid ":c:data:`PyTrace_CALL`" msgstr "" #: ../../c-api/init.rst:2000 ../../c-api/init.rst:2005 #: ../../c-api/init.rst:2016 msgid "Always :c:data:`Py_None`." msgstr "" #: ../../c-api/init.rst:2002 msgid ":c:data:`PyTrace_EXCEPTION`" msgstr "" #: ../../c-api/init.rst:2002 msgid "Exception information as returned by :func:`sys.exc_info`." msgstr "" #: ../../c-api/init.rst:2005 msgid ":c:data:`PyTrace_LINE`" msgstr "" #: ../../c-api/init.rst:2007 msgid ":c:data:`PyTrace_RETURN`" msgstr "" #: ../../c-api/init.rst:2007 msgid "" "Value being returned to the caller, or ``NULL`` if caused by an exception." msgstr "" #: ../../c-api/init.rst:2010 msgid ":c:data:`PyTrace_C_CALL`" msgstr "" #: ../../c-api/init.rst:2010 ../../c-api/init.rst:2012 #: ../../c-api/init.rst:2014 msgid "Function object being called." msgstr "" #: ../../c-api/init.rst:2012 msgid ":c:data:`PyTrace_C_EXCEPTION`" msgstr "" #: ../../c-api/init.rst:2014 msgid ":c:data:`PyTrace_C_RETURN`" msgstr "" #: ../../c-api/init.rst:2016 msgid ":c:data:`PyTrace_OPCODE`" msgstr "" #: ../../c-api/init.rst:2021 msgid "" "The value of the *what* parameter to a :c:type:`Py_tracefunc` function when " "a new call to a function or method is being reported, or a new entry into a " "generator. Note that the creation of the iterator for a generator function " "is not reported as there is no control transfer to the Python bytecode in " "the corresponding frame." msgstr "" #: ../../c-api/init.rst:2030 msgid "" "The value of the *what* parameter to a :c:type:`Py_tracefunc` function when " "an exception has been raised. The callback function is called with this " "value for *what* when after any bytecode is processed after which the " "exception becomes set within the frame being executed. The effect of this " "is that as exception propagation causes the Python stack to unwind, the " "callback is called upon return to each frame as the exception propagates. " "Only trace functions receives these events; they are not needed by the " "profiler." msgstr "" #: ../../c-api/init.rst:2041 msgid "" "The value passed as the *what* parameter to a :c:type:`Py_tracefunc` " "function (but not a profiling function) when a line-number event is being " "reported. It may be disabled for a frame by setting " ":attr:`~frame.f_trace_lines` to *0* on that frame." msgstr "" #: ../../c-api/init.rst:2049 msgid "" "The value for the *what* parameter to :c:type:`Py_tracefunc` functions when " "a call is about to return." msgstr "" #: ../../c-api/init.rst:2055 msgid "" "The value for the *what* parameter to :c:type:`Py_tracefunc` functions when " "a C function is about to be called." msgstr "" #: ../../c-api/init.rst:2061 msgid "" "The value for the *what* parameter to :c:type:`Py_tracefunc` functions when " "a C function has raised an exception." msgstr "" #: ../../c-api/init.rst:2067 msgid "" "The value for the *what* parameter to :c:type:`Py_tracefunc` functions when " "a C function has returned." msgstr "" #: ../../c-api/init.rst:2073 msgid "" "The value for the *what* parameter to :c:type:`Py_tracefunc` functions (but " "not profiling functions) when a new opcode is about to be executed. This " "event is not emitted by default: it must be explicitly requested by setting " ":attr:`~frame.f_trace_opcodes` to *1* on the frame." msgstr "" #: ../../c-api/init.rst:2081 msgid "" "Set the profiler function to *func*. The *obj* parameter is passed to the " "function as its first parameter, and may be any Python object, or ``NULL``." " If the profile function needs to maintain state, using a different value " "for *obj* for each thread provides a convenient and thread-safe place to " "store it. The profile function is called for all monitored events except " ":c:data:`PyTrace_LINE` :c:data:`PyTrace_OPCODE` and " ":c:data:`PyTrace_EXCEPTION`." msgstr "" #: ../../c-api/init.rst:2088 msgid "See also the :func:`sys.setprofile` function." msgstr "" #: ../../c-api/init.rst:2094 msgid "" "Like :c:func:`PyEval_SetProfile` but sets the profile function in all " "running threads belonging to the current interpreter instead of the setting " "it only on the current thread." msgstr "" #: ../../c-api/init.rst:2099 msgid "" "As :c:func:`PyEval_SetProfile`, this function ignores any exceptions raised " "while setting the profile functions in all threads." msgstr "" #: ../../c-api/init.rst:2107 msgid "" "Set the tracing function to *func*. This is similar to " ":c:func:`PyEval_SetProfile`, except the tracing function does receive line-" "number events and per-opcode events, but does not receive any event related " "to C function objects being called. Any trace function registered using " ":c:func:`PyEval_SetTrace` will not receive :c:data:`PyTrace_C_CALL`, " ":c:data:`PyTrace_C_EXCEPTION` or :c:data:`PyTrace_C_RETURN` as a value for " "the *what* parameter." msgstr "" #: ../../c-api/init.rst:2114 msgid "See also the :func:`sys.settrace` function." msgstr "" #: ../../c-api/init.rst:2120 msgid "" "Like :c:func:`PyEval_SetTrace` but sets the tracing function in all running " "threads belonging to the current interpreter instead of the setting it only " "on the current thread." msgstr "" #: ../../c-api/init.rst:2125 msgid "" "As :c:func:`PyEval_SetTrace`, this function ignores any exceptions raised " "while setting the trace functions in all threads." msgstr "" #: ../../c-api/init.rst:2131 msgid "Reference tracing" msgstr "" #: ../../c-api/init.rst:2137 msgid "" "The type of the trace function registered using " ":c:func:`PyRefTracer_SetTracer`. The first parameter is a Python object that" " has been just created (when **event** is set to " ":c:data:`PyRefTracer_CREATE`) or about to be destroyed (when **event** is " "set to :c:data:`PyRefTracer_DESTROY`). The **data** argument is the opaque " "pointer that was provided when :c:func:`PyRefTracer_SetTracer` was called." msgstr "" #: ../../c-api/init.rst:2147 msgid "" "The value for the *event* parameter to :c:type:`PyRefTracer` functions when " "a Python object has been created." msgstr "" #: ../../c-api/init.rst:2152 msgid "" "The value for the *event* parameter to :c:type:`PyRefTracer` functions when " "a Python object has been destroyed." msgstr "" #: ../../c-api/init.rst:2157 msgid "" "Register a reference tracer function. The function will be called when a new" " Python has been created or when an object is going to be destroyed. If " "**data** is provided it must be an opaque pointer that will be provided when" " the tracer function is called. Return ``0`` on success. Set an exception " "and return ``-1`` on error." msgstr "" #: ../../c-api/init.rst:2163 msgid "" "Not that tracer functions **must not** create Python objects inside or " "otherwise the call will be re-entrant. The tracer also **must not** clear " "any existing exception or set an exception. A :term:`thread state` will be " "active every time the tracer function is called." msgstr "" #: ../../c-api/init.rst:2168 ../../c-api/init.rst:2179 msgid "" "There must be an :term:`attached thread state` when calling this function." msgstr "" #: ../../c-api/init.rst:2174 msgid "" "Get the registered reference tracer function and the value of the opaque " "data pointer that was registered when :c:func:`PyRefTracer_SetTracer` was " "called. If no tracer was registered this function will return NULL and will " "set the **data** pointer to NULL." msgstr "" #: ../../c-api/init.rst:2186 msgid "Advanced Debugger Support" msgstr "" #: ../../c-api/init.rst:2191 msgid "" "These functions are only intended to be used by advanced debugging tools." msgstr "" #: ../../c-api/init.rst:2196 msgid "" "Return the interpreter state object at the head of the list of all such " "objects." msgstr "" #: ../../c-api/init.rst:2201 msgid "Return the main interpreter state object." msgstr "" #: ../../c-api/init.rst:2206 msgid "" "Return the next interpreter state object after *interp* from the list of all" " such objects." msgstr "" #: ../../c-api/init.rst:2212 msgid "" "Return the pointer to the first :c:type:`PyThreadState` object in the list " "of threads associated with the interpreter *interp*." msgstr "" #: ../../c-api/init.rst:2218 msgid "" "Return the next thread state object after *tstate* from the list of all such" " objects belonging to the same :c:type:`PyInterpreterState` object." msgstr "" #: ../../c-api/init.rst:2225 msgid "Thread Local Storage Support" msgstr "" #: ../../c-api/init.rst:2229 msgid "" "The Python interpreter provides low-level support for thread-local storage " "(TLS) which wraps the underlying native TLS implementation to support the " "Python-level thread local storage API (:class:`threading.local`). The " "CPython C level APIs are similar to those offered by pthreads and Windows: " "use a thread key and functions to associate a :c:expr:`void*` value per " "thread." msgstr "" #: ../../c-api/init.rst:2236 msgid "" "A :term:`thread state` does *not* need to be :term:`attached ` when calling these functions; they suppl their own locking." msgstr "" #: ../../c-api/init.rst:2239 msgid "" "Note that :file:`Python.h` does not include the declaration of the TLS APIs," " you need to include :file:`pythread.h` to use thread-local storage." msgstr "" #: ../../c-api/init.rst:2243 msgid "" "None of these API functions handle memory management on behalf of the " ":c:expr:`void*` values. You need to allocate and deallocate them yourself. " "If the :c:expr:`void*` values happen to be :c:expr:`PyObject*`, these " "functions don't do refcount operations on them either." msgstr "" #: ../../c-api/init.rst:2251 msgid "Thread Specific Storage (TSS) API" msgstr "" #: ../../c-api/init.rst:2253 msgid "" "TSS API is introduced to supersede the use of the existing TLS API within " "the CPython interpreter. This API uses a new type :c:type:`Py_tss_t` " "instead of :c:expr:`int` to represent thread keys." msgstr "" #: ../../c-api/init.rst:2259 msgid "\"A New C-API for Thread-Local Storage in CPython\" (:pep:`539`)" msgstr "" #: ../../c-api/init.rst:2264 msgid "" "This data structure represents the state of a thread key, the definition of " "which may depend on the underlying TLS implementation, and it has an " "internal field representing the key's initialization state. There are no " "public members in this structure." msgstr "" #: ../../c-api/init.rst:2269 msgid "" "When :ref:`Py_LIMITED_API ` is not defined, static allocation of " "this type by :c:macro:`Py_tss_NEEDS_INIT` is allowed." msgstr "" #: ../../c-api/init.rst:2275 msgid "" "This macro expands to the initializer for :c:type:`Py_tss_t` variables. Note" " that this macro won't be defined with :ref:`Py_LIMITED_API `." msgstr "" #: ../../c-api/init.rst:2280 msgid "Dynamic Allocation" msgstr "" #: ../../c-api/init.rst:2282 msgid "" "Dynamic allocation of the :c:type:`Py_tss_t`, required in extension modules " "built with :ref:`Py_LIMITED_API `, where static allocation of this " "type is not possible due to its implementation being opaque at build time." msgstr "" #: ../../c-api/init.rst:2289 msgid "" "Return a value which is the same state as a value initialized with " ":c:macro:`Py_tss_NEEDS_INIT`, or ``NULL`` in the case of dynamic allocation " "failure." msgstr "" #: ../../c-api/init.rst:2296 msgid "" "Free the given *key* allocated by :c:func:`PyThread_tss_alloc`, after first " "calling :c:func:`PyThread_tss_delete` to ensure any associated thread locals" " have been unassigned. This is a no-op if the *key* argument is ``NULL``." msgstr "" #: ../../c-api/init.rst:2302 msgid "" "A freed key becomes a dangling pointer. You should reset the key to " "``NULL``." msgstr "" #: ../../c-api/init.rst:2307 msgid "Methods" msgstr "Metode-Metode" #: ../../c-api/init.rst:2309 msgid "" "The parameter *key* of these functions must not be ``NULL``. Moreover, the " "behaviors of :c:func:`PyThread_tss_set` and :c:func:`PyThread_tss_get` are " "undefined if the given :c:type:`Py_tss_t` has not been initialized by " ":c:func:`PyThread_tss_create`." msgstr "" #: ../../c-api/init.rst:2317 msgid "" "Return a non-zero value if the given :c:type:`Py_tss_t` has been initialized" " by :c:func:`PyThread_tss_create`." msgstr "" #: ../../c-api/init.rst:2323 msgid "" "Return a zero value on successful initialization of a TSS key. The behavior" " is undefined if the value pointed to by the *key* argument is not " "initialized by :c:macro:`Py_tss_NEEDS_INIT`. This function can be called " "repeatedly on the same key -- calling it on an already initialized key is a " "no-op and immediately returns success." msgstr "" #: ../../c-api/init.rst:2332 msgid "" "Destroy a TSS key to forget the values associated with the key across all " "threads, and change the key's initialization state to uninitialized. A " "destroyed key is able to be initialized again by " ":c:func:`PyThread_tss_create`. This function can be called repeatedly on the" " same key -- calling it on an already destroyed key is a no-op." msgstr "" #: ../../c-api/init.rst:2341 msgid "" "Return a zero value to indicate successfully associating a :c:expr:`void*` " "value with a TSS key in the current thread. Each thread has a distinct " "mapping of the key to a :c:expr:`void*` value." msgstr "" #: ../../c-api/init.rst:2348 msgid "" "Return the :c:expr:`void*` value associated with a TSS key in the current " "thread. This returns ``NULL`` if no value is associated with the key in the" " current thread." msgstr "" #: ../../c-api/init.rst:2356 msgid "Thread Local Storage (TLS) API" msgstr "" #: ../../c-api/init.rst:2358 msgid "" "This API is superseded by :ref:`Thread Specific Storage (TSS) API `." msgstr "" #: ../../c-api/init.rst:2363 msgid "" "This version of the API does not support platforms where the native TLS key " "is defined in a way that cannot be safely cast to ``int``. On such " "platforms, :c:func:`PyThread_create_key` will return immediately with a " "failure status, and the other TLS functions will all be no-ops on such " "platforms." msgstr "" #: ../../c-api/init.rst:2368 msgid "" "Due to the compatibility problem noted above, this version of the API should" " not be used in new code." msgstr "" #: ../../c-api/init.rst:2379 msgid "Synchronization Primitives" msgstr "" #: ../../c-api/init.rst:2381 msgid "The C-API provides a basic mutual exclusion lock." msgstr "" #: ../../c-api/init.rst:2385 msgid "" "A mutual exclusion lock. The :c:type:`!PyMutex` should be initialized to " "zero to represent the unlocked state. For example::" msgstr "" #: ../../c-api/init.rst:2388 msgid "PyMutex mutex = {0};" msgstr "" #: ../../c-api/init.rst:2390 msgid "" "Instances of :c:type:`!PyMutex` should not be copied or moved. Both the " "contents and address of a :c:type:`!PyMutex` are meaningful, and it must " "remain at a fixed, writable location in memory." msgstr "" #: ../../c-api/init.rst:2396 msgid "" "A :c:type:`!PyMutex` currently occupies one byte, but the size should be " "considered unstable. The size may change in future Python releases without " "a deprecation period." msgstr "" #: ../../c-api/init.rst:2404 msgid "" "Lock mutex *m*. If another thread has already locked it, the calling thread" " will block until the mutex is unlocked. While blocked, the thread will " "temporarily detach the :term:`thread state ` if one " "exists." msgstr "" #: ../../c-api/init.rst:2412 msgid "" "Unlock mutex *m*. The mutex must be locked --- otherwise, the function will " "issue a fatal error." msgstr "" #: ../../c-api/init.rst:2420 msgid "Python Critical Section API" msgstr "" #: ../../c-api/init.rst:2422 msgid "" "The critical section API provides a deadlock avoidance layer on top of per-" "object locks for :term:`free-threaded ` CPython. They are " "intended to replace reliance on the :term:`global interpreter lock`, and are" " no-ops in versions of Python with the global interpreter lock." msgstr "" #: ../../c-api/init.rst:2427 msgid "" "Critical sections avoid deadlocks by implicitly suspending active critical " "sections and releasing the locks during calls to " ":c:func:`PyEval_SaveThread`. When :c:func:`PyEval_RestoreThread` is called, " "the most recent critical section is resumed, and its locks reacquired. This" " means the critical section API provides weaker guarantees than traditional " "locks -- they are useful because their behavior is similar to the " ":term:`GIL`." msgstr "" #: ../../c-api/init.rst:2434 msgid "" "The functions and structs used by the macros are exposed for cases where C " "macros are not available. They should only be used as in the given macro " "expansions. Note that the sizes and contents of the structures may change in" " future Python versions." msgstr "" #: ../../c-api/init.rst:2441 msgid "" "Operations that need to lock two objects at once must use " ":c:macro:`Py_BEGIN_CRITICAL_SECTION2`. You *cannot* use nested critical " "sections to lock more than one object at once, because the inner critical " "section may suspend the outer critical sections. This API does not provide " "a way to lock more than two objects at once." msgstr "" #: ../../c-api/init.rst:2447 msgid "Example usage::" msgstr "" #: ../../c-api/init.rst:2449 msgid "" "static PyObject *\n" "set_field(MyObject *self, PyObject *value)\n" "{\n" " Py_BEGIN_CRITICAL_SECTION(self);\n" " Py_SETREF(self->field, Py_XNewRef(value));\n" " Py_END_CRITICAL_SECTION();\n" " Py_RETURN_NONE;\n" "}" msgstr "" #: ../../c-api/init.rst:2458 msgid "" "In the above example, :c:macro:`Py_SETREF` calls :c:macro:`Py_DECREF`, which" " can call arbitrary code through an object's deallocation function. The " "critical section API avoids potential deadlocks due to reentrancy and lock " "ordering by allowing the runtime to temporarily suspend the critical section" " if the code triggered by the finalizer blocks and calls " ":c:func:`PyEval_SaveThread`." msgstr "" #: ../../c-api/init.rst:2466 msgid "" "Acquires the per-object lock for the object *op* and begins a critical " "section." msgstr "" #: ../../c-api/init.rst:2469 ../../c-api/init.rst:2483 #: ../../c-api/init.rst:2498 ../../c-api/init.rst:2512 msgid "In the free-threaded build, this macro expands to::" msgstr "" #: ../../c-api/init.rst:2471 msgid "" "{\n" " PyCriticalSection _py_cs;\n" " PyCriticalSection_Begin(&_py_cs, (PyObject*)(op))" msgstr "" #: ../../c-api/init.rst:2475 ../../c-api/init.rst:2504 msgid "In the default build, this macro expands to ``{``." msgstr "" #: ../../c-api/init.rst:2481 msgid "Ends the critical section and releases the per-object lock." msgstr "" #: ../../c-api/init.rst:2485 msgid "" " PyCriticalSection_End(&_py_cs);\n" "}" msgstr "" #: ../../c-api/init.rst:2488 ../../c-api/init.rst:2517 msgid "In the default build, this macro expands to ``}``." msgstr "" #: ../../c-api/init.rst:2494 msgid "" "Acquires the per-objects locks for the objects *a* and *b* and begins a " "critical section. The locks are acquired in a consistent order (lowest " "address first) to avoid lock ordering deadlocks." msgstr "" #: ../../c-api/init.rst:2500 msgid "" "{\n" " PyCriticalSection2 _py_cs2;\n" " PyCriticalSection2_Begin(&_py_cs2, (PyObject*)(a), (PyObject*)(b))" msgstr "" #: ../../c-api/init.rst:2510 msgid "Ends the critical section and releases the per-object locks." msgstr "" #: ../../c-api/init.rst:2514 msgid "" " PyCriticalSection2_End(&_py_cs2);\n" "}" msgstr "" #: ../../c-api/init.rst:350 msgid "PyEval_InitThreads()" msgstr "" #: ../../c-api/init.rst:350 msgid "modules (in module sys)" msgstr "" #: ../../c-api/init.rst:350 ../../c-api/init.rst:726 msgid "path (in module sys)" msgstr "" #: ../../c-api/init.rst:350 ../../c-api/init.rst:726 ../../c-api/init.rst:1208 #: ../../c-api/init.rst:1723 ../../c-api/init.rst:1822 msgid "module" msgstr "modul" #: ../../c-api/init.rst:350 ../../c-api/init.rst:1723 #: ../../c-api/init.rst:1822 msgid "builtins" msgstr "builtins" #: ../../c-api/init.rst:350 ../../c-api/init.rst:1723 #: ../../c-api/init.rst:1822 msgid "__main__" msgstr "" #: ../../c-api/init.rst:350 ../../c-api/init.rst:1723 #: ../../c-api/init.rst:1822 msgid "sys" msgstr "sys" #: ../../c-api/init.rst:350 ../../c-api/init.rst:726 msgid "search" msgstr "" #: ../../c-api/init.rst:350 ../../c-api/init.rst:726 msgid "path" msgstr "" #: ../../c-api/init.rst:350 ../../c-api/init.rst:1787 #: ../../c-api/init.rst:1840 msgid "Py_FinalizeEx (C function)" msgstr "" #: ../../c-api/init.rst:586 msgid "Py_Initialize()" msgstr "" #: ../../c-api/init.rst:586 ../../c-api/init.rst:824 msgid "main()" msgstr "" #: ../../c-api/init.rst:586 msgid "Py_GetPath()" msgstr "" #: ../../c-api/init.rst:704 msgid "executable (in module sys)" msgstr "" #: ../../c-api/init.rst:759 ../../c-api/init.rst:801 ../../c-api/init.rst:815 msgid "version (in module sys)" msgstr "" #: ../../c-api/init.rst:771 msgid "platform (in module sys)" msgstr "" #: ../../c-api/init.rst:788 msgid "copyright (in module sys)" msgstr "" #: ../../c-api/init.rst:824 msgid "Py_FatalError()" msgstr "" #: ../../c-api/init.rst:824 msgid "argv (in module sys)" msgstr "" #: ../../c-api/init.rst:944 msgid "global interpreter lock" msgstr "kunci interpreter global" #: ../../c-api/init.rst:944 msgid "interpreter lock" msgstr "" #: ../../c-api/init.rst:944 msgid "lock, interpreter" msgstr "" #: ../../c-api/init.rst:958 msgid "setswitchinterval (in module sys)" msgstr "" #: ../../c-api/init.rst:967 msgid "PyThreadState (C type)" msgstr "" #: ../../c-api/init.rst:1003 msgid "Py_BEGIN_ALLOW_THREADS (C macro)" msgstr "" #: ../../c-api/init.rst:1003 msgid "Py_END_ALLOW_THREADS (C macro)" msgstr "" #: ../../c-api/init.rst:1019 msgid "PyEval_RestoreThread (C function)" msgstr "" #: ../../c-api/init.rst:1019 msgid "PyEval_SaveThread (C function)" msgstr "" #: ../../c-api/init.rst:1186 msgid "PyEval_AcquireThread()" msgstr "" #: ../../c-api/init.rst:1186 msgid "PyEval_ReleaseThread()" msgstr "" #: ../../c-api/init.rst:1186 msgid "PyEval_SaveThread()" msgstr "" #: ../../c-api/init.rst:1186 msgid "PyEval_RestoreThread()" msgstr "" #: ../../c-api/init.rst:1208 msgid "_thread" msgstr "" #: ../../c-api/init.rst:1723 ../../c-api/init.rst:1822 msgid "stdout (in module sys)" msgstr "" #: ../../c-api/init.rst:1723 ../../c-api/init.rst:1822 msgid "stderr (in module sys)" msgstr "" #: ../../c-api/init.rst:1723 ../../c-api/init.rst:1822 msgid "stdin (in module sys)" msgstr "" #: ../../c-api/init.rst:1787 msgid "Py_Initialize (C function)" msgstr "" #: ../../c-api/init.rst:1817 msgid "close (in module os)" msgstr ""