@@ -105,45 +105,63 @@ defined closer to where they are useful (e.g. :c:macro:`Py_RETURN_NONE`).
105105Others of a more general utility are defined here. This is not necessarily a
106106complete listing.
107107
108- .. c :macro :: Py_UNREACHABLE( )
108+ .. c :macro :: Py_ABS(x )
109109
110- Use this when you have a code path that cannot be reached by design.
111- For example, in the ``default: `` clause in a ``switch `` statement for which
112- all possible values are covered in ``case `` statements. Use this in places
113- where you might be tempted to put an ``assert(0) `` or ``abort() `` call.
110+ Return the absolute value of ``x ``.
114111
115- In release mode, the macro helps the compiler to optimize the code, and
116- avoids a warning about unreachable code. For example, the macro is
117- implemented with ``__builtin_unreachable() `` on GCC in release mode.
112+ .. versionadded :: 3.3
118113
119- A use for ``Py_UNREACHABLE() `` is following a call a function that
120- never returns but that is not declared :c:macro: `_Py_NO_RETURN `.
114+ .. c :macro :: Py_CHARMASK(c)
121115
122- If a code path is very unlikely code but can be reached under exceptional
123- case, this macro must not be used. For example, under low memory condition
124- or if a system call returns a value out of the expected range. In this
125- case, it's better to report the error to the caller. If the error cannot
126- be reported to caller, :c:func: `Py_FatalError ` can be used.
116+ Argument must be a character or an integer in the range [-128, 127] or [0,
117+ 255]. This macro returns ``c `` cast to an ``unsigned char ``.
127118
128- .. versionadded :: 3.7
119+ .. c : macro :: Py_DEPRECATED(version)
129120
130- .. c :macro :: Py_ABS(x)
121+ Use this for deprecated declarations. The macro must be placed before the
122+ symbol name.
131123
132- Return the absolute value of ``x ``.
124+ Example::
125+
126+ Py_DEPRECATED(3.8) PyAPI_FUNC(int) Py_OldFunction(void);
127+
128+ .. versionchanged :: 3.8
129+ MSVC support was added.
130+
131+ .. c :macro :: Py_GETENV(s)
132+
133+ Like ``getenv(s) ``, but returns ``NULL `` if :option: `-E ` was passed on the
134+ command line (i.e. if ``Py_IgnoreEnvironmentFlag `` is set).
135+
136+ .. c :macro :: Py_MAX(x, y)
137+
138+ Return the maximum value between ``x `` and ``y ``.
133139
134140 .. versionadded :: 3.3
135141
142+ .. c :macro :: Py_MEMBER_SIZE(type, member)
143+
144+ Return the size of a structure (``type ``) ``member `` in bytes.
145+
146+ .. versionadded :: 3.6
147+
136148.. c :macro :: Py_MIN(x, y)
137149
138150 Return the minimum value between ``x `` and ``y ``.
139151
140152 .. versionadded :: 3.3
141153
142- .. c :macro :: Py_MAX(x, y)
154+ .. c :macro :: Py_NO_INLINE
143155
144- Return the maximum value between ``x `` and ``y ``.
156+ Disable inlining on a function. For example, it reduces the C stack
157+ consumption: useful on LTO+PGO builds which heavily inline code (see
158+ :issue: `33720 `).
145159
146- .. versionadded :: 3.3
160+ Usage::
161+
162+ Py_NO_INLINE static int random(void) { return 4; }
163+
164+ .. versionadded :: 3.11
147165
148166.. c :macro :: Py_STRINGIFY(x)
149167
@@ -152,21 +170,27 @@ complete listing.
152170
153171 .. versionadded :: 3.4
154172
155- .. c :macro :: Py_MEMBER_SIZE(type, member)
156-
157- Return the size of a structure (``type ``) ``member `` in bytes.
173+ .. c :macro :: Py_UNREACHABLE()
158174
159- .. versionadded :: 3.6
175+ Use this when you have a code path that cannot be reached by design.
176+ For example, in the ``default: `` clause in a ``switch `` statement for which
177+ all possible values are covered in ``case `` statements. Use this in places
178+ where you might be tempted to put an ``assert(0) `` or ``abort() `` call.
160179
161- .. c :macro :: Py_CHARMASK(c)
180+ In release mode, the macro helps the compiler to optimize the code, and
181+ avoids a warning about unreachable code. For example, the macro is
182+ implemented with ``__builtin_unreachable() `` on GCC in release mode.
162183
163- Argument must be a character or an integer in the range [-128, 127] or [0,
164- 255]. This macro returns `` c `` cast to an `` unsigned char ` `.
184+ A use for `` Py_UNREACHABLE() `` is following a call a function that
185+ never returns but that is not declared :c:macro: ` _Py_NO_RETURN `.
165186
166- .. c :macro :: Py_GETENV(s)
187+ If a code path is very unlikely code but can be reached under exceptional
188+ case, this macro must not be used. For example, under low memory condition
189+ or if a system call returns a value out of the expected range. In this
190+ case, it's better to report the error to the caller. If the error cannot
191+ be reported to caller, :c:func: `Py_FatalError ` can be used.
167192
168- Like ``getenv(s) ``, but returns ``NULL `` if :option: `-E ` was passed on the
169- command line (i.e. if ``Py_IgnoreEnvironmentFlag `` is set).
193+ .. versionadded :: 3.7
170194
171195.. c :macro :: Py_UNUSED(arg)
172196
@@ -175,18 +199,6 @@ complete listing.
175199
176200 .. versionadded :: 3.4
177201
178- .. c :macro :: Py_DEPRECATED(version)
179-
180- Use this for deprecated declarations. The macro must be placed before the
181- symbol name.
182-
183- Example::
184-
185- Py_DEPRECATED(3.8) PyAPI_FUNC(int) Py_OldFunction(void);
186-
187- .. versionchanged :: 3.8
188- MSVC support was added.
189-
190202.. c :macro :: PyDoc_STRVAR(name, str)
191203
192204 Creates a variable with name ``name `` that can be used in docstrings.
@@ -221,6 +233,7 @@ complete listing.
221233 {NULL, NULL}
222234 };
223235
236+
224237.. _api-objects :
225238
226239Objects, Types and Reference Counts
0 commit comments