1.1 --- a/docs/wiki/Servers Sat Jan 23 19:19:54 2021 +0100
1.2 +++ b/docs/wiki/Servers Sat Jan 23 19:20:28 2021 +0100
1.3 @@ -234,14 +234,24 @@
1.4 IPC gate was involved in delivering the message.
1.5
1.6 The details of waiting for messages, testing the label, and directing requests
1.7 -to the component are dealt with by another convenience function:
1.8 +to the component are dealt with by another convenience function (or macro,
1.9 +more accurately):
1.10
1.11 {{{
1.12 -ipc_server_loop(Calc_expected_items, &obj, (ipc_server_handler_type) handle_Calc);
1.13 +ipc_server_loop_for(Calc, &obj);
1.14 }}}
1.15
1.16 Here, the following parameters are specified:
1.17
1.18 + * The interface type involved
1.19 +
1.20 + * The object address which is used to check message labels
1.21 +
1.22 +=== Technical Details ===
1.23 +
1.24 +This macro invocation expands to a call to `ipc_server_loop` with the
1.25 +following parameters:
1.26 +
1.27 * The predefined number of items expected for the `Calc` interface, generated
1.28 automatically and provided by `Calc_expected_items`
1.29
1.30 @@ -251,6 +261,26 @@
1.31 provided by the generated `handle_Calc` function which must be cast to an
1.32 acceptable type as indicated
1.33
1.34 +Here, the macro casts the object address to the appropriate type. In simple
1.35 +cases, this is a superfluous operation since the object type will be directly
1.36 +compatible with the interface type used to expose the object, and such a
1.37 +casting operation will not change the address. However, in more complicated
1.38 +cases such as where an object type inherits from the interface type and one or
1.39 +more other types, such a casting operation may change the address.
1.40 +
1.41 +It is important to note that the IPC handling mechanism treats the object
1.42 +address as an opaque value, presenting it to the handler function for
1.43 +interpretation as a pointer to an object of the interface type. Where the
1.44 +object type is directly compatible (such that casting to the interface type
1.45 +does not change the address), this reinterpretation of the address will be
1.46 +correct. Where the type is not directly compatible, however, (such that
1.47 +casting to the interface type does change the address) the reinterpretation is
1.48 +incorrect: subsequent accesses via the pointer will be erroneous.
1.49 +
1.50 +Consequently, it is essential to perform casting to the interface type before
1.51 +the address is presented to the IPC handling mechanism. The macro is provided
1.52 +to ensure that this step is not overlooked.
1.53 +
1.54 == Example Code ==
1.55
1.56 The `pkg/idl4re-examples` directory contains some example packages for L4Re
2.1 --- a/pkg/idl4re-examples/calc++/server.cc Sat Jan 23 19:19:54 2021 +0100
2.2 +++ b/pkg/idl4re-examples/calc++/server.cc Sat Jan 23 19:20:28 2021 +0100
2.3 @@ -1,7 +1,7 @@
2.4 /*
2.5 * Provide a calculation server.
2.6 *
2.7 - * Copyright (C) 2020 Paul Boddie <paul@boddie.org.uk>
2.8 + * Copyright (C) 2020, 2021 Paul Boddie <paul@boddie.org.uk>
2.9 *
2.10 * This program is free software; you can redistribute it and/or
2.11 * modify it under the terms of the GNU General Public License as
2.12 @@ -91,8 +91,7 @@
2.13
2.14 /* Wait for messages, dispatching to the handler. */
2.15
2.16 - ipc_server_loop(Calc_expected_items, &obj,
2.17 - (ipc_server_handler_type) handle_Calc);
2.18 + ipc_server_loop_for(Calc, &obj);
2.19
2.20 return 0;
2.21 }
3.1 --- a/pkg/idl4re-examples/calc++/server_compound.cc Sat Jan 23 19:19:54 2021 +0100
3.2 +++ b/pkg/idl4re-examples/calc++/server_compound.cc Sat Jan 23 19:20:28 2021 +0100
3.3 @@ -1,7 +1,7 @@
3.4 /*
3.5 * Provide a server offering a compound interface.
3.6 *
3.7 - * Copyright (C) 2020 Paul Boddie <paul@boddie.org.uk>
3.8 + * Copyright (C) 2020, 2021 Paul Boddie <paul@boddie.org.uk>
3.9 *
3.10 * This program is free software; you can redistribute it and/or
3.11 * modify it under the terms of the GNU General Public License as
3.12 @@ -102,8 +102,7 @@
3.13
3.14 /* Wait for messages, dispatching to the handler. */
3.15
3.16 - ipc_server_loop(CalcCounter_expected_items, &obj,
3.17 - (ipc_server_handler_type) handle_CalcCounter);
3.18 + ipc_server_loop_for(CalcCounter, &obj);
3.19
3.20 return 0;
3.21 }
4.1 --- a/pkg/idl4re-examples/calc/server.c Sat Jan 23 19:19:54 2021 +0100
4.2 +++ b/pkg/idl4re-examples/calc/server.c Sat Jan 23 19:20:28 2021 +0100
4.3 @@ -1,7 +1,7 @@
4.4 /*
4.5 * Provide a calculation server.
4.6 *
4.7 - * Copyright (C) 2020 Paul Boddie <paul@boddie.org.uk>
4.8 + * Copyright (C) 2020, 2021 Paul Boddie <paul@boddie.org.uk>
4.9 *
4.10 * This program is free software; you can redistribute it and/or
4.11 * modify it under the terms of the GNU General Public License as
4.12 @@ -105,8 +105,7 @@
4.13
4.14 /* Wait for messages, dispatching to the handler. */
4.15
4.16 - ipc_server_loop(Calc_expected_items, &obj,
4.17 - (ipc_server_handler_type) handle_Calc);
4.18 + ipc_server_loop_for(Calc, &obj);
4.19
4.20 return 0;
4.21 }
5.1 --- a/pkg/idl4re-examples/calc/server_compound.c Sat Jan 23 19:19:54 2021 +0100
5.2 +++ b/pkg/idl4re-examples/calc/server_compound.c Sat Jan 23 19:20:28 2021 +0100
5.3 @@ -1,7 +1,7 @@
5.4 /*
5.5 * Provide a server offering a compound interface.
5.6 *
5.7 - * Copyright (C) 2020 Paul Boddie <paul@boddie.org.uk>
5.8 + * Copyright (C) 2020, 2021 Paul Boddie <paul@boddie.org.uk>
5.9 *
5.10 * This program is free software; you can redistribute it and/or
5.11 * modify it under the terms of the GNU General Public License as
5.12 @@ -131,8 +131,7 @@
5.13
5.14 /* Wait for messages, dispatching to the handler. */
5.15
5.16 - ipc_server_loop(CalcCounter_expected_items, &obj,
5.17 - (ipc_server_handler_type) handle_CalcCounter);
5.18 + ipc_server_loop_for(CalcCounter, &obj);
5.19
5.20 return 0;
5.21 }