@@ -105,45 +105,63 @@ defined closer to where they are useful (e.g. :c:macro:`Py_RETURN_NONE`).
105
105
Others of a more general utility are defined here. This is not necessarily a
106
106
complete listing.
107
107
108
- .. c :macro :: Py_UNREACHABLE( )
108
+ .. c :macro :: Py_ABS(x )
109
109
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 ``.
114
111
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
118
113
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)
121
115
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 ``.
127
118
128
- .. versionadded :: 3.7
119
+ .. c : macro :: Py_DEPRECATED(version)
129
120
130
- .. c :macro :: Py_ABS(x)
121
+ Use this for deprecated declarations. The macro must be placed before the
122
+ symbol name.
131
123
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 ``.
133
139
134
140
.. versionadded :: 3.3
135
141
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
+
136
148
.. c :macro :: Py_MIN(x, y)
137
149
138
150
Return the minimum value between ``x `` and ``y ``.
139
151
140
152
.. versionadded :: 3.3
141
153
142
- .. c :macro :: Py_MAX(x, y)
154
+ .. c :macro :: Py_NO_INLINE
143
155
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 `).
145
159
146
- .. versionadded :: 3.3
160
+ Usage::
161
+
162
+ Py_NO_INLINE static int random(void) { return 4; }
163
+
164
+ .. versionadded :: 3.11
147
165
148
166
.. c :macro :: Py_STRINGIFY(x)
149
167
@@ -152,21 +170,27 @@ complete listing.
152
170
153
171
.. versionadded :: 3.4
154
172
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()
158
174
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.
160
179
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.
162
183
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 `.
165
186
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.
167
192
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
170
194
171
195
.. c :macro :: Py_UNUSED(arg)
172
196
@@ -175,18 +199,6 @@ complete listing.
175
199
176
200
.. versionadded :: 3.4
177
201
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
-
190
202
.. c :macro :: PyDoc_STRVAR(name, str)
191
203
192
204
Creates a variable with name ``name `` that can be used in docstrings.
@@ -221,6 +233,7 @@ complete listing.
221
233
{NULL, NULL}
222
234
};
223
235
236
+
224
237
.. _api-objects :
225
238
226
239
Objects, Types and Reference Counts
0 commit comments