All of lore.kernel.org
 help / color / mirror / Atom feed
From: "Alex Bennée" <alex.bennee@linaro.org>
To: qemu-devel@nongnu.org
Cc: fam@euphon.net, berrange@redhat.com,
	"Philippe Mathieu-Daudé" <philmd@redhat.com>,
	f4bug@amsat.org, stefanha@redhat.com, crosa@redhat.com,
	pbonzini@redhat.com, "Alex Bennée" <alex.bennee@linaro.org>,
	aurelien@aurel32.net
Subject: [PATCH v1 24/34] docs/devel: more documentation on the use of suffixes
Date: Wed,  5 Jan 2022 13:49:59 +0000	[thread overview]
Message-ID: <20220105135009.1584676-25-alex.bennee@linaro.org> (raw)
In-Reply-To: <20220105135009.1584676-1-alex.bennee@linaro.org>

Using _qemu is a little confusing. Let's use _compat for these sorts
of things. We should also mention _impl which is another common suffix
in the code base.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com>
Message-Id: <20211217171902.2668674-1-alex.bennee@linaro.org>

---
v2
  - use Paolo's suggested wording for _impl
---
 docs/devel/style.rst  | 6 ++++++
 include/glib-compat.h | 6 +++---
 2 files changed, 9 insertions(+), 3 deletions(-)

diff --git a/docs/devel/style.rst b/docs/devel/style.rst
index 4f770002a7..793a8d4280 100644
--- a/docs/devel/style.rst
+++ b/docs/devel/style.rst
@@ -151,6 +151,12 @@ If there are two versions of a function to be called with or without a
 lock held, the function that expects the lock to be already held
 usually uses the suffix ``_locked``.
 
+If a function is a shim designed to deal with compatibility
+workarounds we use the suffix ``_compat``. These are generally not
+called directly and aliased to the plain function name via the
+pre-processor. Another common suffix is ``_impl``; it is used for the
+concrete implementation of a function that will not be called
+directly, but rather through a macro or an inline function.
 
 Block structure
 ===============
diff --git a/include/glib-compat.h b/include/glib-compat.h
index 8d01a8c01f..3113a7d2af 100644
--- a/include/glib-compat.h
+++ b/include/glib-compat.h
@@ -46,9 +46,9 @@
  *    int g_foo(const char *wibble)
  *
  * We must define a static inline function with the same signature that does
- * what we need, but with a "_qemu" suffix e.g.
+ * what we need, but with a "_compat" suffix e.g.
  *
- * static inline void g_foo_qemu(const char *wibble)
+ * static inline void g_foo_compat(const char *wibble)
  * {
  *     #if GLIB_CHECK_VERSION(X, Y, 0)
  *        g_foo(wibble)
@@ -61,7 +61,7 @@
  * ensuring this wrapper function impl doesn't trigger the compiler warning
  * about using too new glib APIs. Finally we can do
  *
- *   #define g_foo(a) g_foo_qemu(a)
+ *   #define g_foo(a) g_foo_compat(a)
  *
  * So now the code elsewhere in QEMU, which *does* have the
  * -Wdeprecated-declarations warning active, can call g_foo(...) as normal,
-- 
2.30.2



  parent reply	other threads:[~2022-01-05 14:21 UTC|newest]

Thread overview: 48+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2022-01-05 13:49 [PATCH v1 00/34] testing/next and other misc fixes Alex Bennée
2022-01-05 13:49 ` [PATCH v1 01/34] ui: avoid compiler warnings from unused clipboard info variable Alex Bennée
2022-01-05 13:49 ` [PATCH v1 02/34] spice: Update QXLInterface for spice >= 0.15.0 Alex Bennée
2022-01-05 13:49 ` [PATCH v1 03/34] meson: require liburing >= 0.3 Alex Bennée
2022-01-05 13:49 ` [PATCH v1 04/34] ui: avoid warnings about directdb on Alpine / musl libc Alex Bennée
2022-01-05 13:49 ` [PATCH v1 05/34] ci: explicitly skip I/O tests on alpine Alex Bennée
2022-01-05 15:14   ` Thomas Huth
2022-01-05 13:49 ` [PATCH v1 06/34] tests/docker: switch fedora image to release 35 Alex Bennée
2022-01-05 13:49 ` [PATCH v1 07/34] tests: integrate lcitool for generating build env manifests Alex Bennée
2022-01-05 13:49 ` [PATCH v1 08/34] tests/docker: auto-generate centos8.docker with lcitool Alex Bennée
2022-01-05 13:49 ` [PATCH v1 09/34] tests/docker: auto-generate fedora.docker " Alex Bennée
2022-01-05 13:49 ` [PATCH v1 10/34] tests/docker: auto-generate ubuntu1804.docker " Alex Bennée
2022-01-05 13:49 ` [PATCH v1 11/34] tests/docker: auto-generate ubuntu2004.docker " Alex Bennée
2022-01-05 13:49 ` [PATCH v1 12/34] tests/docker: auto-generate opensuse-leap.docker " Alex Bennée
2022-01-05 13:49 ` [PATCH v1 13/34] tests/docker: remove ubuntu.docker container Alex Bennée
2022-01-05 13:49 ` [PATCH v1 14/34] .gitlab-ci.d/cirrus: auto-generate variables with lcitool Alex Bennée
2022-01-05 13:49 ` [PATCH v1 15/34] tests/docker: updates to alpine package list Alex Bennée
2022-01-05 13:49 ` [PATCH v1 16/34] tests/docker: fix sorting of alpine image package lists Alex Bennée
2022-01-05 13:49 ` [PATCH v1 17/34] tests/docker: fully expand the alpine package list Alex Bennée
2022-01-05 13:49 ` [PATCH v1 18/34] tests/docker: auto-generate alpine.docker with lcitool Alex Bennée
2022-01-05 13:49 ` [PATCH v1 19/34] tests/tcg: use CONFIG_LINUX_USER, not CONFIG_LINUX Alex Bennée
2022-01-10  9:58   ` Philippe Mathieu-Daudé
2022-01-16 23:22     ` Warner Losh
2022-01-05 13:49 ` [PATCH v1 20/34] tests/docker: add libfuse3 development headers Alex Bennée
2022-01-05 14:26   ` Richard W.M. Jones
2022-01-05 14:50     ` Daniel P. Berrangé
2022-01-05 13:49 ` [PATCH v1 21/34] hw/arm: add control knob to disable kaslr_seed via DTB Alex Bennée
2022-01-05 14:49   ` Andrew Jones
2022-01-06 17:21   ` Peter Maydell
2022-01-05 13:49 ` [PATCH v1 22/34] monitor: move x-query-profile into accel/tcg to fix build Alex Bennée
2022-01-05 13:49 ` [PATCH v1 23/34] docs/devel: update C standard to C11 Alex Bennée
2022-01-05 13:49 ` Alex Bennée [this message]
2022-01-05 13:50 ` [PATCH v1 25/34] linux-user/elfload: add extra logging for hole finding Alex Bennée
2022-01-07  0:11   ` Richard Henderson
2022-01-10  9:53   ` Philippe Mathieu-Daudé
2022-01-10 21:50   ` Warner Losh
2022-01-05 13:50 ` [PATCH v1 26/34] linux-user: don't adjust base of found hole Alex Bennée
2022-01-05 13:50 ` [PATCH v1 27/34] tests/avocado: add :avocado: tags for some tests Alex Bennée
2022-01-10  9:56   ` Philippe Mathieu-Daudé
2022-01-10 10:20     ` Alex Bennée
2022-01-10 21:11   ` Beraldo Leal
2022-01-05 13:50 ` [PATCH v1 28/34] tests/tcg/multiarch: Read fp flags before printf Alex Bennée
2022-01-05 13:50 ` [PATCH v1 29/34] test/tcg/ppc64le: Add float reference files Alex Bennée
2022-01-05 13:50 ` [PATCH v1 30/34] FreeBSD: Upgrade to 12.3 release Alex Bennée
2022-01-05 13:50 ` [PATCH v1 31/34] docs/sphinx: fix compatibility with sphinx < 1.8 Alex Bennée
2022-01-05 13:50 ` [PATCH v1 32/34] gitlab-ci: Enable docs in the centos job Alex Bennée
2022-01-05 13:50 ` [PATCH v1 33/34] docker: include bison in debian-tricore-cross Alex Bennée
2022-01-05 13:50 ` [PATCH v1 34/34] linux-user: Remove the deprecated ppc64abi32 target Alex Bennée

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20220105135009.1584676-25-alex.bennee@linaro.org \
    --to=alex.bennee@linaro.org \
    --cc=aurelien@aurel32.net \
    --cc=berrange@redhat.com \
    --cc=crosa@redhat.com \
    --cc=f4bug@amsat.org \
    --cc=fam@euphon.net \
    --cc=pbonzini@redhat.com \
    --cc=philmd@redhat.com \
    --cc=qemu-devel@nongnu.org \
    --cc=stefanha@redhat.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.