luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-01-14 08:16:24 +01:00
Code Issues Packages Projects Releases Wiki Activity

Provide examples for GNUC attribute macros

Browse Source 
It isn't always obvious how and where to use these. Where possible I've
chosen real examples from GLib, preferring simple examples that
developers considering using these macros have hopefully already seen.

Signed-off-by: Simon McVittie <smcv@collabora.com>
This commit is contained in:
Simon McVittie 2019-03-13 15:45:23 +00:00
parent b94a0fc2b4
commit 1e3793546d
2 changed files with 106 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
glib/docs.c
View File

@ -2054,6 +2054,16 @@
* This macro can be used either inside or outside of a function body,
* but must appear on a line by itself.
*
* |[<!-- language="C" --
* static void
* test_deprecated_function (void)
* {
* G_GNUC_BEGIN_IGNORE_DEPRECATIONS
* g_assert_cmpint (my_mistake (), ==, 42);
* G_GNUC_END_IGNORE_DEPRECATIONS
* }
* ]|
*
* Since: 2.32
*/
@ -2078,6 +2088,11 @@
* meant to be portable across different compilers and must be placed
* before the function declaration.
*
* |[<!-- language="C" --
* G_DEPRECATED
* int my_mistake (void);
* ]|
*
* Since: 2.32
*/
@ -2090,6 +2105,11 @@
* is meant to be portable across different compilers and must be placed
* before the function declaration.
*
* |[<!-- language="C" --
* G_DEPRECATED_FOR(my_replacement)
* int my_mistake (void);
* ]|
*
* Since: 2.32
*/

88
glib/gmacros.h
View File

@ -106,6 +106,10 @@
*
* Place the attribute after the declaration, just before the semicolon.
*
* |[<!-- language="C" -->
* gboolean g_type_check_value (const GValue *value) G_GNUC_PURE;
* ]|
*
* See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-pure-function-attribute) for more details.
*/
@ -132,6 +136,10 @@
*
* Place the attribute after the declaration, just before the semicolon.
*
* |[<!-- language="C" -->
* gpointer g_malloc (gsize n_bytes) G_GNUC_MALLOC G_GNUC_ALLOC_SIZE(1);
* ]|
*
* See the
* [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-functions-that-behave-like-malloc)
* for more details.
@ -148,8 +156,17 @@
* Declaring a function as `noinline` prevents the function from being
* considered for inlining.
*
* The attribute may be placed before the declaration, right before the
* `static` keyword.
* The attribute may be placed before the declaration or definition,
* right before the `static` keyword.
*
* |[<!-- language="C" -->
* G_GNUC_NO_INLINE
* static int
* do_not_inline_this (void)
* {
* ...
* }
* ]|
*
* See the
* [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-noinline-function-attribute)
@ -178,6 +195,11 @@
*
* Place the attribute after the declaration, just before the semicolon.
*
* |[<!-- language="C" -->
* gchar *g_strconcat (const gchar *string1,
* ...) G_GNUC_NULL_TERMINATED;
* ]|
*
* See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-sentinel-function-attribute) for more details.
*
* Since: 2.8
@ -240,6 +262,10 @@
* Place the attribute after the function declaration, just before the
* semicolon.
*
* |[<!-- language="C" -->
* gpointer g_malloc (gsize n_bytes) G_GNUC_MALLOC G_GNUC_ALLOC_SIZE(1);
* ]|
*
* See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-alloc_005fsize-function-attribute) for more details.
*
* Since: 2.18
@ -258,6 +284,11 @@
* Place the attribute after the function declaration, just before the
* semicolon.
*
* |[<!-- language="C" -->
* gpointer g_malloc_n (gsize n_blocks,
* gsize n_block_bytes) G_GNUC_MALLOC G_GNUC_ALLOC_SIZE2(1, 2);
* ]|
*
* See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-alloc_005fsize-function-attribute) for more details.
*
* Since: 2.18
@ -310,6 +341,15 @@
* arguments, with the same syntax as `scanf()`. It allows the compiler
* to type-check the arguments passed to the function.
*
* |[<!-- language="C" -->
* int my_scanf (MyStream *stream,
* const char *format,
* ...) G_GNUC_SCANF (2, 3);
* int my_vscanf (MyStream *stream,
* const char *format,
* va_list ap) G_GNUC_SCANF (2, 0);
* ]|
*
* See the
* [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-Wformat-3288)
* for details.
@ -325,6 +365,12 @@
* which is passed to `strftime()` or an API implementing its formats. It allows
* the compiler check the format passed to the function.
*
* |[<!-- language="C" -->
* gsize my_strftime (MyBuffer *buffer,
* const char *format,
* const struct tm *tm) G_GNUC_STRFTIME (2);
* ]|
*
* See the
* [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-Wformat-3288)
* for details.
@ -363,6 +409,10 @@
*
* Place the attribute after the declaration, just before the semicolon.
*
* |[<!-- language="C" -->
* void g_abort (void) G_GNUC_NORETURN;
* ]|
*
* See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-noreturn-function-attribute) for more details.
*/
@ -376,6 +426,10 @@
*
* Place the attribute after the declaration, just before the semicolon.
*
* |[<!-- language="C" -->
* gchar g_ascii_tolower (gchar c) G_GNUC_CONST;
* ]|
*
* See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-const-function-attribute) for more details.
*
* A function that has pointer arguments and examines the data pointed to
@ -413,6 +467,10 @@
*
* Place the attribute after the declaration, just before the semicolon.
*
* |[<!-- language="C" -->
* int do_uninteresting_things (void) G_GNUC_NO_INSTRUMENT;
* ]|
*
* See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-no_005finstrument_005ffunction-function-attribute) for more details.
*/
@ -468,6 +526,19 @@
* Put the attribute right before the case statement you want to fall through
* to.
*
* |[<!-- language="C" -->
* switch (foo)
* {
* case 1:
* g_message ("it's 1");
* G_GNUC_FALLTHROUGH;
* case 2:
* g_message ("it's either 1 or 2");
* break;
* }
* ]|
*
*
* See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Statement-Attributes.html#index-fallthrough-statement-attribute) for more details.
*
* Since: 2.60
@ -488,6 +559,10 @@
*
* Place the attribute after the declaration, just before the semicolon.
*
* |[<!-- language="C" -->
* int my_mistake (void) G_GNUC_DEPRECATED;
* ]|
*
* See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-deprecated-function-attribute) for more details.
*
* Since: 2.2
@ -509,6 +584,10 @@
*
* Place the attribute after the declaration, just before the semicolon.
*
* |[<!-- language="C" -->
* int my_mistake (void) G_GNUC_DEPRECATED_FOR(my_replacement);
* ]|
*
* See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-deprecated-function-attribute) for more details.
*
* Note that if @f is a macro, it will be expanded in the warning message.
@ -579,6 +658,11 @@
*
* Place the attribute after the declaration, just before the semicolon.
*
* |[<!-- language="C" -->
* GList *g_list_append (GList *list,
* gpointer data) G_GNUC_WARN_UNUSED_RESULT;
* ]|
*
* See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-warn_005funused_005fresult-function-attribute) for more details.
*
* Since: 2.10