Skip to contentSkip to conversation

HACKING: Document 'struct' keyword usage

PATCH In review Eduardo Habkost 3 participants 3 messages Aug 12, 2019 – Aug 13, 2019

lore
Share & tools
lore
#0 lore raw

PATCH v2 1/1 HACKING: Document 'struct' keyword usage

Sometimes we use the 'struct' keyword in headers to help us reduce dependencies between header files. Document that practice.

---
Changes v1 -> v2:
* Use paragraphs written by Paolo Bonzini at
https://www.mail-archive.com/[email protected]/msg586214.html
* Fix typos spotted by Thomas Huth

---
 HACKING | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)
HACKING +13 -1
index 0fc3e0fc04..035276e668 100644
@@ -100,7 +100,19 @@ pointer, you're guaranteed that it is used to modify the storage
 it points to, or it is aliased to another pointer that is.
 
 2.3. Typedefs
-Typedefs are used to eliminate the redundant 'struct' keyword.
+
+Typedefs are used to eliminate the redundant 'struct' keyword, since type
+names have a different style than other identifiers ("CamelCase" versus
+"snake_case").  Each struct should have a CamelCase name and a
+corresponding typedef.
+
+Since certain C compilers choke on duplicated typedefs, you should avoid
+them and declare a typedef only in one header file.  For common types,
+you can use "include/qemu/typedefs.h" for example.  However, as a matter
+of convenience it is also perfectly fine to use forward struct
+definitions instead of typedefs in headers and function prototypes; this
+avoids problems with duplicated typedefs and reduces the need to include
+headers from other headers.
 
 2.4. Reserved namespaces in C and POSIX
 Underscore capital, double underscore, and underscore 't' suffixes should be
Signature · 1 line
2.21.0
Reviewed-by on v2 1/1
#1 lore raw
Quoted 20 lines · Eduardo Habkost

Sometimes we use the 'struct' keyword in headers to help us reduce dependencies between header files. Document that practice.

---
Changes v1 -> v2:
* Use paragraphs written by Paolo Bonzini at
https://www.mail-archive.com/[email protected]/msg586214.html
* Fix typos spotted by Thomas Huth

---
 HACKING | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)
HACKING +0 -0
index 0fc3e0fc04..035276e668 100644

HACKING pointer, you're guaranteed that it is used to modify the storage · line 106

Quoted 8 lines
HACKING +4 -1
@@ -100,7 +100,19 @@ pointer, you're guaranteed that it is used to modify the storage
 it points to, or it is aliased to another pointer that is.
 
 2.3. Typedefs
-Typedefs are used to eliminate the redundant 'struct' keyword.
+
+Typedefs are used to eliminate the redundant 'struct' keyword, since type
+names have a different style than other identifiers ("CamelCase" versus
+"snake_case").  Each struct should have a CamelCase name and a

Maybe s/Each struct/Each global struct/ ? Or "non-local" or something similar? Sometimes, you also define a struct just within a function, and in that case we don't require the typedef, do we?

HACKING pointer, you're guaranteed that it is used to modify the storage · line 115

Quoted 9 lines
HACKING +9 -0
+corresponding typedef.
+
+Since certain C compilers choke on duplicated typedefs, you should avoid
+them and declare a typedef only in one header file.  For common types,
+you can use "include/qemu/typedefs.h" for example.  However, as a matter
+of convenience it is also perfectly fine to use forward struct
+definitions instead of typedefs in headers and function prototypes; this
+avoids problems with duplicated typedefs and reduces the need to include
+headers from other headers.
#2 lore raw
Quoted 3 lines · Thomas Huth

Maybe s/Each struct/Each global struct/ ? Or "non-local" or something similar? Sometimes, you also define a struct just within a function, and in that case we don't require the typedef, do we?

I changed it to "each named struct" and queued.

Thanks,

Paolo