Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(156)

Side by Side Diff: ipc/ipc_message_macros.h

Issue 1284593004: Fix a few typos in the IPC message macros documentation (Closed) Base URL: https://chromium.googlesource.com/chromium/src.git@master
Patch Set: Created 5 years, 4 months ago
Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.
Jump to:
View unified diff | Download patch
« no previous file with comments | « no previous file | no next file » | no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
1 // Copyright (c) 2012 The Chromium Authors. All rights reserved. 1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be 2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file. 3 // found in the LICENSE file.
4 4
5 // Defining IPC Messages 5 // Defining IPC Messages
6 // 6 //
7 // Your IPC messages will be defined by macros inside of an XXX_messages.h 7 // Your IPC messages will be defined by macros inside of an XXX_messages.h
8 // header file. Most of the time, the system can automatically generate all 8 // header file. Most of the time, the system can automatically generate all
9 // of messaging mechanism from these definitions, but sometimes some manual 9 // of messaging mechanism from these definitions, but sometimes some manual
10 // coding is required. In these cases, you will also have an XXX_messages.cc 10 // coding is required. In these cases, you will also have an XXX_messages.cc
11 // implemation file as well. 11 // implementation file as well.
12 // 12 //
13 // The senders of your messages will include your XXX_messages.h file to 13 // The senders of your messages will include your XXX_messages.h file to
14 // get the full set of definitions they need to send your messages. 14 // get the full set of definitions they need to send your messages.
15 // 15 //
16 // Each XXX_messages.h file must be registered with the IPC system. This 16 // Each XXX_messages.h file must be registered with the IPC system. This
17 // requires adding two things: 17 // requires adding two things:
18 // - An XXXMsgStart value to the IPCMessageStart enum in ipc_message_start.h 18 // - An XXXMsgStart value to the IPCMessageStart enum in ipc_message_start.h
19 // - An inclusion of XXX_messages.h file in a message generator .h file 19 // - An inclusion of XXX_messages.h file in a message generator .h file
20 // 20 //
21 // The XXXMsgStart value is an enumeration that ensures uniqueness for 21 // The XXXMsgStart value is an enumeration that ensures uniqueness for
22 // each different message file. Later, you will use this inside your 22 // each different message file. Later, you will use this inside your
23 // XXX_messages.h file before invoking message declaration macros: 23 // XXX_messages.h file before invoking message declaration macros:
24 // #define IPC_MESSAGE_START XXXMsgStart 24 // #define IPC_MESSAGE_START XXXMsgStart
25 // ( ... your macro invocations go here ... ) 25 // ( ... your macro invocations go here ... )
26 // 26 //
27 // Message Generator Files 27 // Message Generator Files
28 // 28 //
29 // A message generator .h header file pulls in all other message-declaring 29 // A message generator .h header file pulls in all other message-declaring
30 // headers for a given component. It is included by a message generator 30 // headers for a given component. It is included by a message generator
31 // .cc file, which is where all the generated code will wind up. Typically, 31 // .cc file, which is where all the generated code will wind up. Typically,
32 // you will use an existing generator (e.g. common_message_generator.cc 32 // you will use an existing generator (e.g. common_message_generator.cc
33 // in /chrome/common), but there are circumstances where you may add a 33 // in /chrome/common), but there are circumstances where you may add a
34 // new one. 34 // new one.
35 // 35 //
36 // In the rare cicrucmstances where you can't re-use an existing file, 36 // In the rare circumstances where you can't re-use an existing file,
37 // your YYY_message_generator.cc file for a component YYY would contain 37 // your YYY_message_generator.cc file for a component YYY would contain
38 // the following code: 38 // the following code:
39 // // Get basic type definitions. 39 // // Get basic type definitions.
40 // #define IPC_MESSAGE_IMPL 40 // #define IPC_MESSAGE_IMPL
41 // #include "path/to/YYY_message_generator.h" 41 // #include "path/to/YYY_message_generator.h"
42 // // Generate constructors. 42 // // Generate constructors.
43 // #include "ipc/struct_constructor_macros.h" 43 // #include "ipc/struct_constructor_macros.h"
44 // #include "path/to/YYY_message_generator.h" 44 // #include "path/to/YYY_message_generator.h"
45 // // Generate destructors. 45 // // Generate destructors.
46 // #include "ipc/struct_destructor_macros.h" 46 // #include "ipc/struct_destructor_macros.h"
(...skipping 18 matching lines...) Expand all
65 // file, put the following after all the includes for param types: 65 // file, put the following after all the includes for param types:
66 // #define IPC_MESSAGE_IMPL 66 // #define IPC_MESSAGE_IMPL
67 // #include "XXX_messages.h" 67 // #include "XXX_messages.h"
68 // (... implementation of traits not auto-generated ...) 68 // (... implementation of traits not auto-generated ...)
69 // 69 //
70 // Multiple Inclusion 70 // Multiple Inclusion
71 // 71 //
72 // The XXX_messages.h file will be multiply-included by the 72 // The XXX_messages.h file will be multiply-included by the
73 // YYY_message_generator.cc file, so your XXX_messages file can't be 73 // YYY_message_generator.cc file, so your XXX_messages file can't be
74 // guarded in the usual manner. Ideally, there will be no need for any 74 // guarded in the usual manner. Ideally, there will be no need for any
75 // inclusion guard, since the XXX_messages.h file should consist soley 75 // inclusion guard, since the XXX_messages.h file should consist solely
76 // of inclusions of other headers (which are self-guarding) and IPC 76 // of inclusions of other headers (which are self-guarding) and IPC
77 // macros (which are multiply evaluating). 77 // macros (which are multiply evaluating).
78 // 78 //
79 // Note that #pragma once cannot be used here; doing so would mark the whole 79 // Note that #pragma once cannot be used here; doing so would mark the whole
80 // file as being singly-included. Since your XXX_messages.h file is only 80 // file as being singly-included. Since your XXX_messages.h file is only
81 // partially-guarded, care must be taken to ensure that it is only included 81 // partially-guarded, care must be taken to ensure that it is only included
82 // by other .cc files (and the YYY_message_generator.h file). Including an 82 // by other .cc files (and the YYY_message_generator.h file). Including an
83 // XXX_messages.h file in some other .h file may result in duplicate 83 // XXX_messages.h file in some other .h file may result in duplicate
84 // declarations and a compilation failure. 84 // declarations and a compilation failure.
85 // 85 //
86 // Type Declarations 86 // Type Declarations
87 // 87 //
88 // It is generally a bad idea to have type definitions in a XXX_messages.h 88 // It is generally a bad idea to have type definitions in a XXX_messages.h
89 // file; most likely the typedef will then be used in the message, as opposed 89 // file; most likely the typedef will then be used in the message, as opposed
90 // to the struct iself. Later, an IPC message dispatcher wil need to call 90 // to the struct itself. Later, an IPC message dispatcher will need to call
91 // a function taking that type, and that function is declared in some other 91 // a function taking that type, and that function is declared in some other
92 // header. Thus, in order to get the type definition, the other header 92 // header. Thus, in order to get the type definition, the other header
93 // would have to include the XXX_messages.h file, violating the rule above 93 // would have to include the XXX_messages.h file, violating the rule above
94 // about not including XXX_messages.h file in other .h files. 94 // about not including XXX_messages.h file in other .h files.
95 // 95 //
96 // One approach here is to move these type definitions to another (guarded) 96 // One approach here is to move these type definitions to another (guarded)
97 // .h file and include this second .h in your XXX_messages.h file. This 97 // .h file and include this second .h in your XXX_messages.h file. This
98 // is still less than ideal, because the dispatched function would have to 98 // is still less than ideal, because the dispatched function would have to
99 // redeclare the typedef or include this second header. This may be 99 // redeclare the typedef or include this second header. This may be
100 // reasonable in a few cases. 100 // reasonable in a few cases.
101 // 101 //
102 // Failing all of the above, then you will want to bracket the smallest 102 // Failing all of the above, then you will want to bracket the smallest
103 // possible section of your XXX_messages.h file containing these types 103 // possible section of your XXX_messages.h file containing these types
104 // with an include guard macro. Be aware that providing an incomplete 104 // with an include guard macro. Be aware that providing an incomplete
105 // class type declaration to avoid pulling in a long chain of headers is 105 // class type declaration to avoid pulling in a long chain of headers is
106 // acceptable when your XXX_messages.h header is being included by the 106 // acceptable when your XXX_messages.h header is being included by the
107 // message sending caller's code, but not when the YYY_message_generator.c 107 // message sending caller's code, but not when the YYY_message_generator.c
108 // is building the messages. In addtion, due to the multiple inclusion 108 // is building the messages. In addition, due to the multiple inclusion
109 // restriction, these type ought to be guarded. Follow a convention like: 109 // restriction, these type ought to be guarded. Follow a convention like:
110 // #ifndef SOME_GUARD_MACRO 110 // #ifndef SOME_GUARD_MACRO
111 // #define SOME_GUARD_MACRO 111 // #define SOME_GUARD_MACRO
112 // class some_class; // One incomplete class declaration 112 // class some_class; // One incomplete class declaration
113 // class_some_other_class; // Another incomplete class declaration 113 // class_some_other_class; // Another incomplete class declaration
114 // #endif // SOME_GUARD_MACRO 114 // #endif // SOME_GUARD_MACRO
115 // #ifdef IPC_MESSAGE_IMPL 115 // #ifdef IPC_MESSAGE_IMPL
116 // #include "path/to/some_class.h" // Full class declaration 116 // #include "path/to/some_class.h" // Full class declaration
117 // #include "path/to/some_other_class.h" // Full class declaration 117 // #include "path/to/some_other_class.h" // Full class declaration
118 // #endif // IPC_MESSAGE_IMPL 118 // #endif // IPC_MESSAGE_IMPL
119 // (.. IPC macros using some_class and some_other_class ...) 119 // (.. IPC macros using some_class and some_other_class ...)
120 // 120 //
121 // Macro Invocations 121 // Macro Invocations
122 // 122 //
123 // You will use IPC message macro invocations for three things: 123 // You will use IPC message macro invocations for three things:
124 // - New struct definitions for IPC 124 // - New struct definitions for IPC
125 // - Registering existing struct and enum definitions with IPC 125 // - Registering existing struct and enum definitions with IPC
126 // - Defining the messages themselves 126 // - Defining the messages themselves
127 // 127 //
128 // New structs are defined with IPC_STRUCT_BEGIN(), IPC_STRUCT_MEMBER(), 128 // New structs are defined with IPC_STRUCT_BEGIN(), IPC_STRUCT_MEMBER(),
129 // IPC_STRUCT_END() family of macros. These cause the XXX_messages.h 129 // IPC_STRUCT_END() family of macros. These cause the XXX_messages.h
130 // to proclaim equivalent struct declarations for use by callers, as well 130 // to proclaim equivalent struct declarations for use by callers, as well
131 // as later registering the type with the message generation. Note that 131 // as later registering the type with the message generation. Note that
132 // IPC_STRUCT_MEMBER() is only permitted inside matching calls to 132 // IPC_STRUCT_MEMBER() is only permitted inside matching calls to
133 // IPC_STRUCT_BEGIN() / IPC_STRUCT_END(). There is also an 133 // IPC_STRUCT_BEGIN() / IPC_STRUCT_END(). There is also an
134 // IPC_STRUCT_BEGIN_WITH_PARENT(), which behaves like IPC_STRUCT_BEGIN(), 134 // IPC_STRUCT_BEGIN_WITH_PARENT(), which behaves like IPC_STRUCT_BEGIN(),
135 // but also accomodates structs that inherit from other structs. 135 // but also accommodates structs that inherit from other structs.
136 // 136 //
137 // Externally-defined structs are registered with IPC_STRUCT_TRAITS_BEGIN(), 137 // Externally-defined structs are registered with IPC_STRUCT_TRAITS_BEGIN(),
138 // IPC_STRUCT_TRAITS_MEMBER(), and IPC_STRUCT_TRAITS_END() macros. These 138 // IPC_STRUCT_TRAITS_MEMBER(), and IPC_STRUCT_TRAITS_END() macros. These
139 // cause registration of the types with message generation only. 139 // cause registration of the types with message generation only.
140 // There's also IPC_STRUCT_TRAITS_PARENT, which is used to register a parent 140 // There's also IPC_STRUCT_TRAITS_PARENT, which is used to register a parent
141 // class (whose own traits are already defined). Note that 141 // class (whose own traits are already defined). Note that
142 // IPC_STRUCT_TRAITS_MEMBER() and IPC_STRUCT_TRAITS_PARENT are only permitted 142 // IPC_STRUCT_TRAITS_MEMBER() and IPC_STRUCT_TRAITS_PARENT are only permitted
143 // inside matching calls to IPC_STRUCT_TRAITS_BEGIN() / 143 // inside matching calls to IPC_STRUCT_TRAITS_BEGIN() /
144 // IPC_STRUCT_TRAITS_END(). 144 // IPC_STRUCT_TRAITS_END().
145 // 145 //
(...skipping 827 matching lines...) Expand 10 before | Expand all | Expand 10 after
973 // This corresponds to an enum value from IPCMessageStart. 973 // This corresponds to an enum value from IPCMessageStart.
974 #define IPC_MESSAGE_CLASS(message) \ 974 #define IPC_MESSAGE_CLASS(message) \
975 IPC_MESSAGE_ID_CLASS(message.type()) 975 IPC_MESSAGE_ID_CLASS(message.type())
976 976
977 #endif // IPC_IPC_MESSAGE_MACROS_H_ 977 #endif // IPC_IPC_MESSAGE_MACROS_H_
978 978
979 // Clean up IPC_MESSAGE_START in this unguarded section so that the 979 // Clean up IPC_MESSAGE_START in this unguarded section so that the
980 // XXX_messages.h files need not do so themselves. This makes the 980 // XXX_messages.h files need not do so themselves. This makes the
981 // XXX_messages.h files easier to write. 981 // XXX_messages.h files easier to write.
982 #undef IPC_MESSAGE_START 982 #undef IPC_MESSAGE_START
OLDNEW
« no previous file with comments | « no previous file | no next file » | no next file with comments »

Powered by Google App Engine
This is Rietveld 408576698