You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@celix.apache.org by "xuzhenbao (via GitHub)" <gi...@apache.org> on 2023/11/23 11:56:30 UTC
[PR] Improve doc (celix)
xuzhenbao opened a new pull request, #690:
URL: https://github.com/apache/celix/pull/690
Improve document for `RSA` and `DFI`
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Improve doc (celix)
Posted by "PengZheng (via GitHub)" <gi...@apache.org>.
PengZheng commented on code in PR #690:
URL: https://github.com/apache/celix/pull/690#discussion_r1403975941
##########
bundles/remote_services/rsa_rpc_json/README.md:
##########
@@ -0,0 +1,68 @@
+---
+title: Remote Service Admin RPC Using JSON
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+## Remote Service Admin RPC Using JSON
+
+Remote service admin RPC does not appear in the OSGI standard document. It is an extraction of the serialization/deserialization functionality from remote service admin. It is part of the remote service admin feature.
+
+`rsa_json_rpc` is a serialization implementation based on [JSON representation](https://amdatu.atlassian.net/wiki/spaces/AMDATUDEV/pages/21954571/Amdatu+Remote#AmdatuRemote-AdminHTTP%2FJson). It uses `libdfi` to convert function invocation information into JSON messages. The interface description is configured through the description file in the interface consumer/provider. See the [libdfi documentation](../../../libs/dfi/README.md) for the interface description file.
+
+### Supported Platform
+- Linux
+
+### Properties/Configuration
+
+| **Properties** | **Type** | **Description**|
+|----------------|----------|----------------|
+| **RSA_JSON_RPC_LOG_CALLS**| bool | If set to true, the RSA will Log calls info to the file in RSA_JSON_RPC_LOG_CALLS_FILE. Default is false. |
+| **RSA_JSON_RPC_LOG_CALLS_FILE**| string | Log file. If RSA_JSON_RPC_LOG_CALLS is enabled, the service calls info will be writen to the file(If restart this bundle, it will truncate file). Default is stdout. |
+
+### Conan Option
+ build_rsa_json_rpc=True Default is False
+
+### CMake Option
+ RSA_JSON_RPC=ON Default is OFF
+
+### Software Design
+
+The implementation of `rsa_json_rpc` includes two parts: 1. Creation of remote service endpoints; 2. Creation of remote service proxies
+
+- Remote service endpoint: It receives remote JSON_RPC requests and calls the corresponding service instances.
+- Remote service proxy: It provides proxy services and serializes service call information (method name, arguments,...) into JSON_RPC requests.
+
+#### The Process Of Creating And Using A Remote Endpoint
+
+When a service is exported, RSA can use rsa_json_rpc to create a service endpoint. When a service is called, the service endpoint calls the corresponding service instance after the RPC request is deserialized. The detailed process is as follows diagram:
+
+
+
+
+#### The Process Of Creating And Using A Remote Proxy
+
+When a service is imported, RSA can use rsa_json_rpc to create a proxy service factory. When a service is called, the proxy service factory creates the proxy service and gives it to the service caller. Then the service proxy serializes the service call information into an RPC request. And the RPC request will be sent to remote endpoint by RSA. The detailed process is as follows diagram:
+
+
+
+In the above process, each consumer of the remote service will have a different service proxy, because the service proxy needs to use the interface description file in the consumer (which may be a bundle) to serialize the service call information.
Review Comment:
This does not feel right. Currently, service descriptor is bundled by its various consumers.
THis is far less than ideal. We'd better let service discovery and RSA fetch service descriptors from service providers at runtime. Alternatively, we can generate the descriptor from the service header, i.e. solve #590.
In the same process, there should be one unique copy of service descriptor for each remote service instance.
##########
bundles/remote_services/discovery_zeroconf/README.md:
##########
@@ -0,0 +1,73 @@
+---
+title: Discovery Zeroconf
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+## Discovery Zeroconf
+
+The `Discovery_zeroconf` is implemented based on [Bonjour](https://github.com/apple-oss-distributions/mDNSResponder), and its operation depends on the mDNS daemon.
+
+The mapping between celix and mdns services is as follows:
+
+| **mDNS service** | **celix service** |
+|------------------|-------------------------------------------|
+| instance name | service name+hash(endpoint uuid) |
+| service type | "_celix-rpc._udp"+${custom subtype} |
+| domain name | "local" |
+| txt record | service properties |
+| host | "celix_rpc_dumb_host.local."(It is dummy) |
+| port | 50009(It is dummy) |
+
+
+Because We will perform the mDNS query only using link-local multicast, so we set domain name default value "local".
+
+To reduce the operation of conversion between host name and address info. we set the address info to txt record, and set the host name and port to a dummy value("celix_rpc_dumb_host.local." and "50009").
Review Comment:
The content of TXT is set by the service provider. This design will force them to watch for address change, which violates the rationale of zeroconf and suggests a severe design flaw. I'll have a good read of RFC 6762 and 6763 this weekend before making further comments on this.
##########
libs/dfi/README.md:
##########
@@ -19,4 +19,243 @@ See the License for the specific language governing permissions and
limitations under the License.
-->
-# Apache Celix Dynamic Function Interface
+## Apache Celix Dynamic Function Interface
+
+Dynamic Function Interface (DFI) is a dynamic interface type implementation based on [libffi](https://en.wikipedia.org/wiki/Libffi).
+It can generate dynamic interface types according to the interface description file, and can convert the corresponding
+dynamic interface call into a [JSON representation](https://amdatu.atlassian.net/wiki/spaces/AMDATUDEV/pages/21954571/Amdatu+Remote#AmdatuRemote-AdminHTTP%2FJson). It can also convert the JSON representation into a dynamic interface call.
+
+### Conan Option
+ build_celix_dfi=True Default is False
+
+### CMake Option
+ CELIX_DFI=ON Default is ON
+
+### Interface Descriptor
+
+In `libdfi`, we have defined a set of simple interface description languages. Users can use this language to describe interface types, and at runtime, libdfi converts the interface description into a dynamic interface.
+
+Before introducing the interface description language, let's look at an example of interface description.
+
+~~~
+:header
+type=interface
+name=calculator
+version=1.0.0
+:annotations
+classname=org.example.Calculator
+:types
+StatsResult={DDD[D average min max input}
+:methods
+add(DD)D=add(#am=handle;PDD#am=pre;*D)N
+~~~
+
+As above, the interface description has four sections: the header section, annotations section, types section, and methods section. The format of each section is as follows:
+
+~~~
+ ':header\n' 'Name=Value\n'...
+ ':annotations\n' 'Name=Value\n'...
+ ':types\n' 'TypeId=Value\n'...
+ ':methods\n' 'MethodId=Value\n'...
+~~~
+
+Among them, the legal characters that can be used in the “name” and “TypeId” include [a-zA-Z0-9_], the legal characters in “MethodId” include [a-zA-Z0-9_] and ".();[{}/". Besides [a-zA-Z0-9], the legal characters in “value” also include ".<>{}[]?;:~!@#$%^&*()_+-=,./'". It's worth noting that there should not be spaces on either side of '=', and each statement must end with a newline(‘\n’).
+
+For the interface description, its header section must include three elements: type, name, version. The value of "type" should be "interface", "name" is the interface name (service name), the value of "version" should coincide with the version number in the actually used interface header file, and it should conform to [semantic versioning requirements](https://semver.org/).
+
+#### The Data Types In The Interface Descriptor
+
+The data types supported by the interface description include:
+
+- **Simple Types**
+
+ *Type schema*:
+
+ |**Identifier**|B |D |F |I |J |S |V |Z |b | i | j | s |P |t |N |
+ |---------|---|------|-----|-------|-------|-------|----|--------------|-----|--------|--------|--------|------|------|---|
+ |**Types**|char|double|float|int32_t|int64_t|int16_t|void|boolean(uint8)|uchar|uint32_t|uint64_t|uint16_t|void *|char *|int|
Review Comment:
Now that we have `*`, why we need `t` for `char *`?
##########
libs/dfi/README.md:
##########
@@ -19,4 +19,243 @@ See the License for the specific language governing permissions and
limitations under the License.
-->
-# Apache Celix Dynamic Function Interface
+## Apache Celix Dynamic Function Interface
+
+Dynamic Function Interface (DFI) is a dynamic interface type implementation based on [libffi](https://en.wikipedia.org/wiki/Libffi).
+It can generate dynamic interface types according to the interface description file, and can convert the corresponding
+dynamic interface call into a [JSON representation](https://amdatu.atlassian.net/wiki/spaces/AMDATUDEV/pages/21954571/Amdatu+Remote#AmdatuRemote-AdminHTTP%2FJson). It can also convert the JSON representation into a dynamic interface call.
+
+### Conan Option
+ build_celix_dfi=True Default is False
+
+### CMake Option
+ CELIX_DFI=ON Default is ON
+
+### Interface Descriptor
+
+In `libdfi`, we have defined a set of simple interface description languages. Users can use this language to describe interface types, and at runtime, libdfi converts the interface description into a dynamic interface.
+
+Before introducing the interface description language, let's look at an example of interface description.
+
+~~~
+:header
+type=interface
+name=calculator
+version=1.0.0
+:annotations
+classname=org.example.Calculator
+:types
+StatsResult={DDD[D average min max input}
+:methods
+add(DD)D=add(#am=handle;PDD#am=pre;*D)N
+~~~
+
+As above, the interface description has four sections: the header section, annotations section, types section, and methods section. The format of each section is as follows:
+
+~~~
+ ':header\n' 'Name=Value\n'...
+ ':annotations\n' 'Name=Value\n'...
+ ':types\n' 'TypeId=Value\n'...
+ ':methods\n' 'MethodId=Value\n'...
+~~~
+
+Among them, the legal characters that can be used in the “name” and “TypeId” include [a-zA-Z0-9_], the legal characters in “MethodId” include [a-zA-Z0-9_] and ".();[{}/". Besides [a-zA-Z0-9], the legal characters in “value” also include ".<>{}[]?;:~!@#$%^&*()_+-=,./'". It's worth noting that there should not be spaces on either side of '=', and each statement must end with a newline(‘\n’).
+
+For the interface description, its header section must include three elements: type, name, version. The value of "type" should be "interface", "name" is the interface name (service name), the value of "version" should coincide with the version number in the actually used interface header file, and it should conform to [semantic versioning requirements](https://semver.org/).
+
+#### The Data Types In The Interface Descriptor
+
+The data types supported by the interface description include:
+
+- **Simple Types**
+
+ *Type schema*:
+
+ |**Identifier**|B |D |F |I |J |S |V |Z |b | i | j | s |P |t |N |
+ |---------|---|------|-----|-------|-------|-------|----|--------------|-----|--------|--------|--------|------|------|---|
+ |**Types**|char|double|float|int32_t|int64_t|int16_t|void|boolean(uint8)|uchar|uint32_t|uint64_t|uint16_t|void *|char *|int|
+
+
+- **Complex Types(Struct)**
+
+ *Type schema*:
+ ~~~
+ {[Type]+ [(Name)(SPACE)]+}
+ ~~~
+ *Example*:
+ ~~~
+ {DDII a b c d}
+ ~~~
+ *To C language*:
+ ~~~
+ struct { double a; double b; int c; int d; };
+ ~~~
+
+- **Sequence Type**
+
+ *Type schema*:
+ ~~~
+ [(type)
+ ~~~
+ *Example*:
+ ~~~
+ [D
+ ~~~
+ *To C language*:
+ ~~~
+ struct {
+ uint32_t cap;
+ uint32_t len;
+ duoble *buf;
+ };
+ ~~~
+
+- **Typed Pointer**
+
+ *Type schema*:
+ ~~~
+ *(Type)
+ ~~~
+ *Example*:
+ ~~~
+ *D
+ ~~~
+ *To C language*:
+ ~~~
+ duoble *d;
+ ~~~
+
+- **Reference By Value**
+
+ *Type schema*:
+ ~~~
+ l(name);
+ ~~~
+ *Example*:
+ ~~~
+ MySubType={jDD time d1 d2}
+ MyType={DDlMySubType; d11 d12 subTypeVal}
+ ~~~
+ *To C language*:
+ ~~~
+ struct MySubType{
+ uint64_t time;
+ double d1;
+ double d2;
+ };
+ struct MyType {
+ double d11;
+ double d12;
+ struct MySubType subTypeVal;
+ };
+ ~~~
+
+- **Pointer Reference**
+
+ *Type schema*:
+ ~~~
+ L(name);//shortcut for *l(name);
Review Comment:
Now that we have `*`, why we need `*l`?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Improve doc (celix)
Posted by "pnoltes (via GitHub)" <gi...@apache.org>.
pnoltes commented on code in PR #690:
URL: https://github.com/apache/celix/pull/690#discussion_r1407919336
##########
bundles/remote_services/README.md:
##########
@@ -33,26 +33,25 @@ The topology manager decides which services should be imported and exported acco
### Remote Service Admin
-The Remote Service Admin (RSA) provides the mechanisms to import and export services when instructed to do so by the Topology Manager.
+The Remote Service Admin (RSA) provides the mechanisms to import and export services when instructed to do so by the Topology Manager.
-#### Endpoints and proxies
+#### Remote Service Admin DFI
-To delegate a *received* method call to the actual service implementation, the RSA uses an "endpoint" bundle, which has all the knowledge about the marshalling and unmarshalling of data for the service. This endpoint bundle is specific to the used RSA implementation, and as such cannot be reused between various RSA implementations.
+Provides remote service admin using HTTP and JSON. The serialization is done using [libdfi](../../libs/dfi/README.md) to convert function call information into [JSON representation](https://amdatu.atlassian.net/wiki/spaces/AMDATUDEV/pages/21954571/Amdatu+Remote#AmdatuRemote-AdminHTTP%2FJson).
+`libffi` is configured using descriptor files in the bundles.
-Invoking a *remote* method is done by using "proxy" bundles. Similar as to endpoints, proxy bundles encapsulate all knowledge to marshall and unmarshall data for a remote method call and as such can not be shared between RSA implementations.
-
-Both proxy and endpoint bundles are loaded on demand when a service is imported or exported by the RSA. As such, these bundles **must** not be added to the list of "auto started" bundles, but placed in a separate location. By default, `endpoints` is used as location for locating proxy and/or endpoint bundles.
-
-Note that since endpoints and proxies need to be created manually, one has full control about the handling of specifics of marshalling and unmarshalling data and dealing with exceptions.
+| **Bundle** | `rsa_dfi.zip` |
Review Comment:
I prefer to use the cmake target names, including the celix alias (e.g. the target downstream users use). So in this case I prefer: `Celix::rsa_dfi`. Ideally we should also start prefix our bundle filenames with a `celix_` prefix.
e..g. as is done with http admin:
```
add_celix_bundle(http_admin
SOURCES
src/http_admin.c
src/websocket_admin.c
src/activator.c
src/service_tree.c
VERSION 1.0.0
SYMBOLIC_NAME "apache_celix_http_admin"
GROUP "Celix/HTTP_admin"
NAME "Apache Celix HTTP Admin"
FILENAME celix_http_admin # <----- ensure that the bundle zip becomes celix_http_admin.zip
)
```
##########
bundles/remote_services/discovery_zeroconf/README.md:
##########
@@ -0,0 +1,73 @@
+---
+title: Discovery Zeroconf
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+## Discovery Zeroconf
+
+The `Discovery_zeroconf` is implemented based on [Bonjour](https://github.com/apple-oss-distributions/mDNSResponder), and its operation depends on the mDNS daemon.
+
+The mapping between celix and mdns services is as follows:
+
+| **mDNS service** | **celix service** |
+|------------------|-------------------------------------------|
+| instance name | service name+hash(endpoint uuid) |
+| service type | "_celix-rpc._udp"+${custom subtype} |
+| domain name | "local" |
+| txt record | service properties |
+| host | "celix_rpc_dumb_host.local."(It is dummy) |
+| port | 50009(It is dummy) |
+
+
+Because We will perform the mDNS query only using link-local multicast, so we set domain name default value "local".
Review Comment:
```suggestion
The domain name value is set to "local" , because for remote discovery the mDNS query will only use link-local multicast.
```
##########
libs/dfi/README.md:
##########
@@ -19,4 +19,243 @@ See the License for the specific language governing permissions and
limitations under the License.
-->
-# Apache Celix Dynamic Function Interface
+## Apache Celix Dynamic Function Interface
+
+Dynamic Function Interface (DFI) is a dynamic interface type implementation based on [libffi](https://en.wikipedia.org/wiki/Libffi).
+It can generate dynamic interface types according to the interface description file, and can convert the corresponding
+dynamic interface call into a [JSON representation](https://amdatu.atlassian.net/wiki/spaces/AMDATUDEV/pages/21954571/Amdatu+Remote#AmdatuRemote-AdminHTTP%2FJson). It can also convert the JSON representation into a dynamic interface call.
+
+### Conan Option
+ build_celix_dfi=True Default is False
+
+### CMake Option
+ CELIX_DFI=ON Default is ON
+
+### Interface Descriptor
+
+In `libdfi`, we have defined a set of simple interface description languages. Users can use this language to describe interface types, and at runtime, libdfi converts the interface description into a dynamic interface.
+
+Before introducing the interface description language, let's look at an example of interface description.
+
+~~~
+:header
+type=interface
+name=calculator
+version=1.0.0
+:annotations
+classname=org.example.Calculator
+:types
+StatsResult={DDD[D average min max input}
+:methods
+add(DD)D=add(#am=handle;PDD#am=pre;*D)N
+~~~
+
+As above, the interface description has four sections: the header section, annotations section, types section, and methods section. The format of each section is as follows:
+
+~~~
+ ':header\n' 'Name=Value\n'...
+ ':annotations\n' 'Name=Value\n'...
+ ':types\n' 'TypeId=Value\n'...
+ ':methods\n' 'MethodId=Value\n'...
+~~~
+
+Among them, the legal characters that can be used in the “name” and “TypeId” include [a-zA-Z0-9_], the legal characters in “MethodId” include [a-zA-Z0-9_] and ".();[{}/". Besides [a-zA-Z0-9], the legal characters in “value” also include ".<>{}[]?;:~!@#$%^&*()_+-=,./'". It's worth noting that there should not be spaces on either side of '=', and each statement must end with a newline(‘\n’).
+
+For the interface description, its header section must include three elements: type, name, version. The value of "type" should be "interface", "name" is the interface name (service name), the value of "version" should coincide with the version number in the actually used interface header file, and it should conform to [semantic versioning requirements](https://semver.org/).
+
+#### The Data Types In The Interface Descriptor
+
+The data types supported by the interface description include:
+
+- **Simple Types**
+
+ *Type schema*:
+
+ |**Identifier**|B |D |F |I |J |S |V |Z |b | i | j | s |P |t |N |
+ |---------|---|------|-----|-------|-------|-------|----|--------------|-----|--------|--------|--------|------|------|---|
+ |**Types**|char|double|float|int32_t|int64_t|int16_t|void|boolean(uint8)|uchar|uint32_t|uint64_t|uint16_t|void *|char *|int|
Review Comment:
I think the `t` is not really necessary anymore. IIRC I added the `t` for 2 reasons:
1) Although C uses a `char*` as string, in other languages a string type is often a special built-in type.
2) In the beginning of libdfi there was not support to specific if something was a pointer or not, so `t` was needed to specify a `char*`, now `*B` can be used.
##########
bundles/remote_services/discovery_zeroconf/README.md:
##########
@@ -0,0 +1,73 @@
+---
+title: Discovery Zeroconf
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+## Discovery Zeroconf
+
+The `Discovery_zeroconf` is implemented based on [Bonjour](https://github.com/apple-oss-distributions/mDNSResponder), and its operation depends on the mDNS daemon.
+
+The mapping between celix and mdns services is as follows:
+
+| **mDNS service** | **celix service** |
+|------------------|-------------------------------------------|
+| instance name | service name+hash(endpoint uuid) |
+| service type | "_celix-rpc._udp"+${custom subtype} |
+| domain name | "local" |
+| txt record | service properties |
+| host | "celix_rpc_dumb_host.local."(It is dummy) |
+| port | 50009(It is dummy) |
+
+
+Because We will perform the mDNS query only using link-local multicast, so we set domain name default value "local".
+
+To reduce the operation of conversion between host name and address info. we set the address info to txt record, and set the host name and port to a dummy value("celix_rpc_dumb_host.local." and "50009").
+
+We set the instance name of the mDNS service as `service_name + hash(endpoint uuid)`. If there is a conflict in the instance name, mDNS_daemon will resolve it. Since the maximum size of the mDNS service instance name is 64 bytes, we take the hash of the endpoint uuid here, which also reduces the probability of instance name conflicts.
Review Comment:
Why is the service name still used, a UUID should be unique enough. Is this for readability/debugging?
##########
bundles/remote_services/discovery_zeroconf/diagrams/service_announce_seq.puml:
##########
Review Comment:
Nice to see the usage of plant UML for some diagrams :smile:
##########
bundles/remote_services/remote_service_admin_shm_v2/diagrams/rsa_shm_remote_service_call_seq.png:
##########
Review Comment:
Again nice to see some sequence diagrams. Especially for a complex sequence like a remote call over the remote service admin :+1:
##########
bundles/remote_services/remote_service_admin_shm_v2/README.md:
##########
@@ -0,0 +1,86 @@
+---
+title: Remote Service Admin SHM
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+## Remote Service Admin SHM
+
+The Celix Remote Service Admin SHM bundle implement OSGi remote service using shared memory.
+In order to reuse the (de)serialization features of remote service admin,
+the remote service admin will be realized by ‘rsa_shm’ and 'rsa_json_rpc'(see [Remote Service Admin RPC Using JSON](../rsa_rpc_json/README.md)) bundles.
+The ‘rsa_shm’ bundle is used to realize ‘remote_service_admin_service_t’ and IPC.
+The ‘rsa_json_rpc’ bundle is used to realize (de)serialization and Creating service endpoint/proxy.
+
+### Supported Platform
+- Linux
+
+### Properties/Configuration
+
+| **Properties** | **Type** | **Description**|
+|----------------|----------|----------------|
+| **rsaShmPoolSize** | long | The RSA SHM pool size in bytes. Its value should be greater than 8192 bytes.(default 256KB) |
Review Comment:
> Its value should be greater than 8192 bytes
why?
##########
bundles/remote_services/remote_service_admin_shm_v2/README.md:
##########
@@ -0,0 +1,86 @@
+---
+title: Remote Service Admin SHM
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+## Remote Service Admin SHM
+
+The Celix Remote Service Admin SHM bundle implement OSGi remote service using shared memory.
+In order to reuse the (de)serialization features of remote service admin,
+the remote service admin will be realized by ‘rsa_shm’ and 'rsa_json_rpc'(see [Remote Service Admin RPC Using JSON](../rsa_rpc_json/README.md)) bundles.
+The ‘rsa_shm’ bundle is used to realize ‘remote_service_admin_service_t’ and IPC.
+The ‘rsa_json_rpc’ bundle is used to realize (de)serialization and Creating service endpoint/proxy.
+
+### Supported Platform
+- Linux
+
+### Properties/Configuration
+
+| **Properties** | **Type** | **Description**|
Review Comment:
Maybe add a colum "**default**"
##########
bundles/remote_services/remote_service_admin_shm_v2/README.md:
##########
@@ -0,0 +1,86 @@
+---
+title: Remote Service Admin SHM
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+## Remote Service Admin SHM
+
+The Celix Remote Service Admin SHM bundle implement OSGi remote service using shared memory.
+In order to reuse the (de)serialization features of remote service admin,
+the remote service admin will be realized by ‘rsa_shm’ and 'rsa_json_rpc'(see [Remote Service Admin RPC Using JSON](../rsa_rpc_json/README.md)) bundles.
+The ‘rsa_shm’ bundle is used to realize ‘remote_service_admin_service_t’ and IPC.
+The ‘rsa_json_rpc’ bundle is used to realize (de)serialization and Creating service endpoint/proxy.
Review Comment:
```suggestion
The ‘rsa_json_rpc’ bundle is used to realize (de)serialization and creating service endpoint/proxy.
```
##########
bundles/remote_services/rsa_rpc_json/README.md:
##########
@@ -0,0 +1,68 @@
+---
+title: Remote Service Admin RPC Using JSON
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+## Remote Service Admin RPC Using JSON
+
+Remote service admin RPC does not appear in the OSGI standard document. It is an extraction of the serialization/deserialization functionality from remote service admin. It is part of the remote service admin feature.
+
+`rsa_json_rpc` is a serialization implementation based on [JSON representation](https://amdatu.atlassian.net/wiki/spaces/AMDATUDEV/pages/21954571/Amdatu+Remote#AmdatuRemote-AdminHTTP%2FJson). It uses `libdfi` to convert function invocation information into JSON messages. The interface description is configured through the description file in the interface consumer/provider. See the [libdfi documentation](../../../libs/dfi/README.md) for the interface description file.
+
+### Supported Platform
+- Linux
+
+### Properties/Configuration
+
+| **Properties** | **Type** | **Description**|
+|----------------|----------|----------------|
+| **RSA_JSON_RPC_LOG_CALLS**| bool | If set to true, the RSA will Log calls info to the file in RSA_JSON_RPC_LOG_CALLS_FILE. Default is false. |
+| **RSA_JSON_RPC_LOG_CALLS_FILE**| string | Log file. If RSA_JSON_RPC_LOG_CALLS is enabled, the service calls info will be writen to the file(If restart this bundle, it will truncate file). Default is stdout. |
+
+### Conan Option
+ build_rsa_json_rpc=True Default is False
+
+### CMake Option
+ RSA_JSON_RPC=ON Default is OFF
+
+### Software Design
+
+The implementation of `rsa_json_rpc` includes two parts: 1. Creation of remote service endpoints; 2. Creation of remote service proxies
+
+- Remote service endpoint: It receives remote JSON_RPC requests and calls the corresponding service instances.
+- Remote service proxy: It provides proxy services and serializes service call information (method name, arguments,...) into JSON_RPC requests.
+
+#### The Process Of Creating And Using A Remote Endpoint
+
+When a service is exported, RSA can use rsa_json_rpc to create a service endpoint. When a service is called, the service endpoint calls the corresponding service instance after the RPC request is deserialized. The detailed process is as follows diagram:
+
+
+
+
+#### The Process Of Creating And Using A Remote Proxy
+
+When a service is imported, RSA can use rsa_json_rpc to create a proxy service factory. When a service is called, the proxy service factory creates the proxy service and gives it to the service caller. Then the service proxy serializes the service call information into an RPC request. And the RPC request will be sent to remote endpoint by RSA. The detailed process is as follows diagram:
Review Comment:
```suggestion
When a service is imported, RSA can use rsa_json_rpc to create a proxy service factory. When a service is requested, the proxy service factory creates the proxy service and gives it to the service requester. Then when the requested service is called (i.e. the service proxy is called), the service proxy serializes the service call information into an RPC request. And the RPC request will be sent to remote endpoint by RSA. The detailed process is as follows diagram:
```
##########
bundles/remote_services/remote_service_admin_shm_v2/README.md:
##########
@@ -0,0 +1,86 @@
+---
+title: Remote Service Admin SHM
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+## Remote Service Admin SHM
+
+The Celix Remote Service Admin SHM bundle implement OSGi remote service using shared memory.
+In order to reuse the (de)serialization features of remote service admin,
+the remote service admin will be realized by ‘rsa_shm’ and 'rsa_json_rpc'(see [Remote Service Admin RPC Using JSON](../rsa_rpc_json/README.md)) bundles.
+The ‘rsa_shm’ bundle is used to realize ‘remote_service_admin_service_t’ and IPC.
+The ‘rsa_json_rpc’ bundle is used to realize (de)serialization and Creating service endpoint/proxy.
+
+### Supported Platform
+- Linux
+
+### Properties/Configuration
+
+| **Properties** | **Type** | **Description**|
+|----------------|----------|----------------|
+| **rsaShmPoolSize** | long | The RSA SHM pool size in bytes. Its value should be greater than 8192 bytes.(default 256KB) |
+| **rsaShmMsgTimeout** | long | The timeout of remote service invocation in seconds. (default 30s) |
+| **rsaShmCctIvNum** | long | The maximum concurrent invocations of the same service. If there are more concurrent invocations than its value, service invocation will fail.(default 32) |
Review Comment:
I did not notice this before, but generally configuration properties follow an all caps naming scheme.
This is done because retrieval of config property fall back to environment variables, and environment variable names are de-facto all caps.
Looking at the `rsa_shm_constants.h` header I also think the define names are more clear then their currently used property/env variable names:
- `RSA_SHM_MEMORY_POOL_SIZE_KEY`
- `RSA_SHM_MSG_TIMEOUT_KEY`
- `RSA_SHM_MAX_CONCURRENT_INVOCATIONS_KEY`
maybe out of scope for this PR, but I think it would be good to update the config property names
##########
bundles/remote_services/rsa_rpc_json/README.md:
##########
@@ -0,0 +1,68 @@
+---
+title: Remote Service Admin RPC Using JSON
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+## Remote Service Admin RPC Using JSON
+
+Remote service admin RPC does not appear in the OSGI standard document. It is an extraction of the serialization/deserialization functionality from remote service admin. It is part of the remote service admin feature.
+
+`rsa_json_rpc` is a serialization implementation based on [JSON representation](https://amdatu.atlassian.net/wiki/spaces/AMDATUDEV/pages/21954571/Amdatu+Remote#AmdatuRemote-AdminHTTP%2FJson). It uses `libdfi` to convert function invocation information into JSON messages. The interface description is configured through the description file in the interface consumer/provider. See the [libdfi documentation](../../../libs/dfi/README.md) for the interface description file.
+
+### Supported Platform
+- Linux
+
+### Properties/Configuration
+
+| **Properties** | **Type** | **Description**|
+|----------------|----------|----------------|
+| **RSA_JSON_RPC_LOG_CALLS**| bool | If set to true, the RSA will Log calls info to the file in RSA_JSON_RPC_LOG_CALLS_FILE. Default is false. |
+| **RSA_JSON_RPC_LOG_CALLS_FILE**| string | Log file. If RSA_JSON_RPC_LOG_CALLS is enabled, the service calls info will be writen to the file(If restart this bundle, it will truncate file). Default is stdout. |
+
+### Conan Option
+ build_rsa_json_rpc=True Default is False
+
+### CMake Option
+ RSA_JSON_RPC=ON Default is OFF
+
+### Software Design
+
+The implementation of `rsa_json_rpc` includes two parts: 1. Creation of remote service endpoints; 2. Creation of remote service proxies
+
+- Remote service endpoint: It receives remote JSON_RPC requests and calls the corresponding service instances.
+- Remote service proxy: It provides proxy services and serializes service call information (method name, arguments,...) into JSON_RPC requests.
+
+#### The Process Of Creating And Using A Remote Endpoint
+
+When a service is exported, RSA can use rsa_json_rpc to create a service endpoint. When a service is called, the service endpoint calls the corresponding service instance after the RPC request is deserialized. The detailed process is as follows diagram:
+
+
+
+
+#### The Process Of Creating And Using A Remote Proxy
+
+When a service is imported, RSA can use rsa_json_rpc to create a proxy service factory. When a service is called, the proxy service factory creates the proxy service and gives it to the service caller. Then the service proxy serializes the service call information into an RPC request. And the RPC request will be sent to remote endpoint by RSA. The detailed process is as follows diagram:
+
+
+
+In the above process, each consumer of the remote service will have a different service proxy, because the service proxy needs to use the interface description file in the consumer (which may be a bundle) to serialize the service call information.
Review Comment:
> In the same process, there should be one unique copy of service descriptor for each remote service instance.
I think this is the key issue. Only 1 unique descriptor for a service per process.
Ideally the consumer and provider are also aligned, but this is not always necessary. It is possible for the provider to provide newer version of the service, as long as it is backwards compatible.
For example a consumer using the following service:
```C
#define FOO_SERVICE_NAME "foo"
#define FOO_SERVICE_VERSION "1.0.0"
struct {
void* handle;
int foo(const char* string);
} my_service
```
Can use a remote! provided service with the following service:
```C
#define FOO_SERVICE_NAME "foo"
#define FOO_SERVICE_VERSION "1.1.0"
struct {
void* handle;
int bar(const char* string);
int foo(const char* string);
} my_service
```
Note that because `bar` is added before `foo` the updated service is not binary backwards compatible inside the same process. But for remote calls, as long as we can identity which method signature is called, different service versions is possible.
For the pubsub serializer handler different version is actual handled:
https://github.com/apache/celix/blob/rel/celix-2.4.0/bundles/pubsub/pubsub_utils/src/pubsub_serializer_handler.c#L237-L242
I also though there was a check on the literal descriptor content, but apparently not.
##########
bundles/remote_services/README.md:
##########
@@ -33,26 +33,25 @@ The topology manager decides which services should be imported and exported acco
### Remote Service Admin
-The Remote Service Admin (RSA) provides the mechanisms to import and export services when instructed to do so by the Topology Manager.
+The Remote Service Admin (RSA) provides the mechanisms to import and export services when instructed to do so by the Topology Manager.
-#### Endpoints and proxies
+#### Remote Service Admin DFI
-To delegate a *received* method call to the actual service implementation, the RSA uses an "endpoint" bundle, which has all the knowledge about the marshalling and unmarshalling of data for the service. This endpoint bundle is specific to the used RSA implementation, and as such cannot be reused between various RSA implementations.
+Provides remote service admin using HTTP and JSON. The serialization is done using [libdfi](../../libs/dfi/README.md) to convert function call information into [JSON representation](https://amdatu.atlassian.net/wiki/spaces/AMDATUDEV/pages/21954571/Amdatu+Remote#AmdatuRemote-AdminHTTP%2FJson).
+`libffi` is configured using descriptor files in the bundles.
-Invoking a *remote* method is done by using "proxy" bundles. Similar as to endpoints, proxy bundles encapsulate all knowledge to marshall and unmarshall data for a remote method call and as such can not be shared between RSA implementations.
-
-Both proxy and endpoint bundles are loaded on demand when a service is imported or exported by the RSA. As such, these bundles **must** not be added to the list of "auto started" bundles, but placed in a separate location. By default, `endpoints` is used as location for locating proxy and/or endpoint bundles.
-
-Note that since endpoints and proxies need to be created manually, one has full control about the handling of specifics of marshalling and unmarshalling data and dealing with exceptions.
+| **Bundle** | `rsa_dfi.zip` |
Review Comment:
this comment applies for the rest of the **Bundle** column values.
##########
libs/dfi/README.md:
##########
@@ -19,4 +19,243 @@ See the License for the specific language governing permissions and
limitations under the License.
-->
-# Apache Celix Dynamic Function Interface
+## Apache Celix Dynamic Function Interface
+
+Dynamic Function Interface (DFI) is a dynamic interface type implementation based on [libffi](https://en.wikipedia.org/wiki/Libffi).
+It can generate dynamic interface types according to the interface description file, and can convert the corresponding
+dynamic interface call into a [JSON representation](https://amdatu.atlassian.net/wiki/spaces/AMDATUDEV/pages/21954571/Amdatu+Remote#AmdatuRemote-AdminHTTP%2FJson). It can also convert the JSON representation into a dynamic interface call.
+
+### Conan Option
+ build_celix_dfi=True Default is False
+
+### CMake Option
+ CELIX_DFI=ON Default is ON
+
+### Interface Descriptor
+
+In `libdfi`, we have defined a set of simple interface description languages. Users can use this language to describe interface types, and at runtime, libdfi converts the interface description into a dynamic interface.
+
+Before introducing the interface description language, let's look at an example of interface description.
+
+~~~
+:header
+type=interface
+name=calculator
+version=1.0.0
+:annotations
+classname=org.example.Calculator
+:types
+StatsResult={DDD[D average min max input}
+:methods
+add(DD)D=add(#am=handle;PDD#am=pre;*D)N
+~~~
+
+As above, the interface description has four sections: the header section, annotations section, types section, and methods section. The format of each section is as follows:
+
+~~~
+ ':header\n' 'Name=Value\n'...
+ ':annotations\n' 'Name=Value\n'...
+ ':types\n' 'TypeId=Value\n'...
+ ':methods\n' 'MethodId=Value\n'...
+~~~
+
+Among them, the legal characters that can be used in the “name” and “TypeId” include [a-zA-Z0-9_], the legal characters in “MethodId” include [a-zA-Z0-9_] and ".();[{}/". Besides [a-zA-Z0-9], the legal characters in “value” also include ".<>{}[]?;:~!@#$%^&*()_+-=,./'". It's worth noting that there should not be spaces on either side of '=', and each statement must end with a newline(‘\n’).
+
+For the interface description, its header section must include three elements: type, name, version. The value of "type" should be "interface", "name" is the interface name (service name), the value of "version" should coincide with the version number in the actually used interface header file, and it should conform to [semantic versioning requirements](https://semver.org/).
+
+#### The Data Types In The Interface Descriptor
+
+The data types supported by the interface description include:
+
+- **Simple Types**
+
+ *Type schema*:
+
+ |**Identifier**|B |D |F |I |J |S |V |Z |b | i | j | s |P |t |N |
+ |---------|---|------|-----|-------|-------|-------|----|--------------|-----|--------|--------|--------|------|------|---|
+ |**Types**|char|double|float|int32_t|int64_t|int16_t|void|boolean(uint8)|uchar|uint32_t|uint64_t|uint16_t|void *|char *|int|
+
+
+- **Complex Types(Struct)**
+
+ *Type schema*:
+ ~~~
+ {[Type]+ [(Name)(SPACE)]+}
+ ~~~
+ *Example*:
+ ~~~
+ {DDII a b c d}
+ ~~~
+ *To C language*:
+ ~~~
+ struct { double a; double b; int c; int d; };
+ ~~~
+
+- **Sequence Type**
+
+ *Type schema*:
+ ~~~
+ [(type)
+ ~~~
+ *Example*:
+ ~~~
+ [D
+ ~~~
+ *To C language*:
+ ~~~
+ struct {
+ uint32_t cap;
+ uint32_t len;
+ duoble *buf;
+ };
+ ~~~
+
+- **Typed Pointer**
+
+ *Type schema*:
+ ~~~
+ *(Type)
+ ~~~
+ *Example*:
+ ~~~
+ *D
+ ~~~
+ *To C language*:
+ ~~~
+ duoble *d;
+ ~~~
+
+- **Reference By Value**
+
+ *Type schema*:
+ ~~~
+ l(name);
+ ~~~
+ *Example*:
+ ~~~
+ MySubType={jDD time d1 d2}
+ MyType={DDlMySubType; d11 d12 subTypeVal}
+ ~~~
+ *To C language*:
+ ~~~
+ struct MySubType{
+ uint64_t time;
+ double d1;
+ double d2;
+ };
+ struct MyType {
+ double d11;
+ double d12;
+ struct MySubType subTypeVal;
+ };
+ ~~~
+
+- **Pointer Reference**
+
+ *Type schema*:
+ ~~~
+ L(name);//shortcut for *l(name);
Review Comment:
Given the support for `*`, I think we can drop `L` and `t` so that we do not have alternatives so "say" the same thing.
##########
bundles/remote_services/remote_service_admin_shm_v2/README.md:
##########
@@ -0,0 +1,86 @@
+---
+title: Remote Service Admin SHM
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+## Remote Service Admin SHM
+
+The Celix Remote Service Admin SHM bundle implement OSGi remote service using shared memory.
+In order to reuse the (de)serialization features of remote service admin,
+the remote service admin will be realized by ‘rsa_shm’ and 'rsa_json_rpc'(see [Remote Service Admin RPC Using JSON](../rsa_rpc_json/README.md)) bundles.
+The ‘rsa_shm’ bundle is used to realize ‘remote_service_admin_service_t’ and IPC.
+The ‘rsa_json_rpc’ bundle is used to realize (de)serialization and Creating service endpoint/proxy.
Review Comment:
```suggestion
The ‘rsa_json_rpc’ bundle is used to realize (de)serialization and creating service endpoint/proxy.
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Improve doc (celix)
Posted by "codecov-commenter (via GitHub)" <gi...@apache.org>.
codecov-commenter commented on PR #690:
URL: https://github.com/apache/celix/pull/690#issuecomment-1965923910
## [Codecov](https://app.codecov.io/gh/apache/celix/pull/690?src=pr&el=h1&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache) Report
All modified and coverable lines are covered by tests :white_check_mark:
> Project coverage is 89.45%. Comparing base [(`423abb8`)](https://app.codecov.io/gh/apache/celix/commit/423abb8a6853ec239c4c944f194a337013c508ce?el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache) to head [(`7b3ea01`)](https://app.codecov.io/gh/apache/celix/pull/690?src=pr&el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache).
> Report is 13 commits behind head on master.
<details><summary>Additional details and impacted files</summary>
```diff
@@ Coverage Diff @@
## master #690 +/- ##
==========================================
+ Coverage 89.32% 89.45% +0.13%
==========================================
Files 216 216
Lines 25153 25294 +141
==========================================
+ Hits 22468 22627 +159
+ Misses 2685 2667 -18
```
</details>
[:umbrella: View full report in Codecov by Sentry](https://app.codecov.io/gh/apache/celix/pull/690?src=pr&el=continue&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache).
:loudspeaker: Have feedback on the report? [Share it here](https://about.codecov.io/codecov-pr-comment-feedback/?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache).
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Improve doc (celix)
Posted by "xuzhenbao (via GitHub)" <gi...@apache.org>.
xuzhenbao merged PR #690:
URL: https://github.com/apache/celix/pull/690
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Improve doc (celix)
Posted by "pnoltes (via GitHub)" <gi...@apache.org>.
pnoltes commented on PR #690:
URL: https://github.com/apache/celix/pull/690#issuecomment-1828528517
It's great to see some sorely missed documentation being added. I will try to review this PR this week.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Improve doc (celix)
Posted by "PengZheng (via GitHub)" <gi...@apache.org>.
PengZheng commented on code in PR #690:
URL: https://github.com/apache/celix/pull/690#discussion_r1411638589
##########
bundles/remote_services/discovery_zeroconf/README.md:
##########
@@ -0,0 +1,73 @@
+---
+title: Discovery Zeroconf
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+## Discovery Zeroconf
+
+The `Discovery_zeroconf` is implemented based on [Bonjour](https://github.com/apple-oss-distributions/mDNSResponder), and its operation depends on the mDNS daemon.
+
+The mapping between celix and mdns services is as follows:
+
+| **mDNS service** | **celix service** |
+|------------------|-------------------------------------------|
+| instance name | service name+hash(endpoint uuid) |
+| service type | "_celix-rpc._udp"+${custom subtype} |
+| domain name | "local" |
+| txt record | service properties |
+| host | "celix_rpc_dumb_host.local."(It is dummy) |
+| port | 50009(It is dummy) |
+
+
+Because We will perform the mDNS query only using link-local multicast, so we set domain name default value "local".
+
+To reduce the operation of conversion between host name and address info. we set the address info to txt record, and set the host name and port to a dummy value("celix_rpc_dumb_host.local." and "50009").
+
+We set the instance name of the mDNS service as `service_name + hash(endpoint uuid)`. If there is a conflict in the instance name, mDNS_daemon will resolve it. Since the maximum size of the mDNS service instance name is 64 bytes, we take the hash of the endpoint uuid here, which also reduces the probability of instance name conflicts.
Review Comment:
Usage of UUID in instance name is explicitly discourage by RFC 6763, the rational of which is explained [here](https://datatracker.ietf.org/doc/html/rfc6763#appendix-D).
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Improve doc (celix)
Posted by "PengZheng (via GitHub)" <gi...@apache.org>.
PengZheng commented on code in PR #690:
URL: https://github.com/apache/celix/pull/690#discussion_r1431232408
##########
libs/dfi/README.md:
##########
@@ -19,4 +19,243 @@ See the License for the specific language governing permissions and
limitations under the License.
-->
-# Apache Celix Dynamic Function Interface
+## Apache Celix Dynamic Function Interface
+
+Dynamic Function Interface (DFI) is a dynamic interface type implementation based on [libffi](https://en.wikipedia.org/wiki/Libffi).
+It can generate dynamic interface types according to the interface description file, and can convert the corresponding
+dynamic interface call into a [JSON representation](https://amdatu.atlassian.net/wiki/spaces/AMDATUDEV/pages/21954571/Amdatu+Remote#AmdatuRemote-AdminHTTP%2FJson). It can also convert the JSON representation into a dynamic interface call.
+
+### Conan Option
+ build_celix_dfi=True Default is False
+
+### CMake Option
+ CELIX_DFI=ON Default is ON
+
+### Interface Descriptor
+
+In `libdfi`, we have defined a set of simple interface description languages. Users can use this language to describe interface types, and at runtime, libdfi converts the interface description into a dynamic interface.
+
+Before introducing the interface description language, let's look at an example of interface description.
+
+~~~
+:header
+type=interface
+name=calculator
+version=1.0.0
+:annotations
+classname=org.example.Calculator
+:types
+StatsResult={DDD[D average min max input}
+:methods
+add(DD)D=add(#am=handle;PDD#am=pre;*D)N
+~~~
+
+As above, the interface description has four sections: the header section, annotations section, types section, and methods section. The format of each section is as follows:
+
+~~~
+ ':header\n' 'Name=Value\n'...
+ ':annotations\n' 'Name=Value\n'...
+ ':types\n' 'TypeId=Value\n'...
+ ':methods\n' 'MethodId=Value\n'...
+~~~
+
+Among them, the legal characters that can be used in the “name” and “TypeId” include [a-zA-Z0-9_], the legal characters in “MethodId” include [a-zA-Z0-9_] and ".();[{}/". Besides [a-zA-Z0-9], the legal characters in “value” also include ".<>{}[]?;:~!@#$%^&*()_+-=,./'". It's worth noting that there should not be spaces on either side of '=', and each statement must end with a newline(‘\n’).
+
+For the interface description, its header section must include three elements: type, name, version. The value of "type" should be "interface", "name" is the interface name (service name), the value of "version" should coincide with the version number in the actually used interface header file, and it should conform to [semantic versioning requirements](https://semver.org/).
+
+#### The Data Types In The Interface Descriptor
+
+The data types supported by the interface description include:
+
+- **Simple Types**
+
+ *Type schema*:
+
+ |**Identifier**|B |D |F |I |J |S |V |Z |b | i | j | s |P |t |N |
+ |---------|---|------|-----|-------|-------|-------|----|--------------|-----|--------|--------|--------|------|------|---|
+ |**Types**|char|double|float|int32_t|int64_t|int16_t|void|boolean(uint8)|uchar|uint32_t|uint64_t|uint16_t|void *|char *|int|
+
+
+- **Complex Types(Struct)**
+
+ *Type schema*:
+ ~~~
+ {[Type]+ [(Name)(SPACE)]+}
+ ~~~
+ *Example*:
+ ~~~
+ {DDII a b c d}
+ ~~~
+ *To C language*:
+ ~~~
+ struct { double a; double b; int c; int d; };
+ ~~~
+
+- **Sequence Type**
+
+ *Type schema*:
+ ~~~
+ [(type)
+ ~~~
+ *Example*:
+ ~~~
+ [D
+ ~~~
+ *To C language*:
+ ~~~
+ struct {
+ uint32_t cap;
+ uint32_t len;
+ duoble *buf;
+ };
+ ~~~
+
+- **Typed Pointer**
+
+ *Type schema*:
+ ~~~
+ *(Type)
+ ~~~
+ *Example*:
+ ~~~
+ *D
+ ~~~
+ *To C language*:
+ ~~~
+ duoble *d;
+ ~~~
+
+- **Reference By Value**
+
+ *Type schema*:
+ ~~~
+ l(name);
+ ~~~
+ *Example*:
+ ~~~
+ MySubType={jDD time d1 d2}
+ MyType={DDlMySubType; d11 d12 subTypeVal}
+ ~~~
+ *To C language*:
+ ~~~
+ struct MySubType{
+ uint64_t time;
+ double d1;
+ double d2;
+ };
+ struct MyType {
+ double d11;
+ double d12;
+ struct MySubType subTypeVal;
+ };
+ ~~~
+
+- **Pointer Reference**
+
+ *Type schema*:
+ ~~~
+ L(name);//shortcut for *l(name);
+ ~~~
+ *Example*:
+ ~~~
+ MySubType={jDD time d1 d2}
+ MyType={DDLMySubType; d11 d12 subTypePtr}
+ ~~~
+ *To C language*:
+ ~~~
+ struct MySubType{
+ uint64_t time;
+ double d1;
+ double d2;
+ };
+ struct MyType {
+ double d11;
+ double d12;
+ struct MySubType *subTypePtr;
+ };
+ ~~~
+
+- **Type Alias（typedef）**
+
+ *Type schema*:
+ ~~~
+ T(Name)=Type;
+ ~~~
+ *Example*:
+ ~~~
+ Ttype={DD val1 val2};{ltype;D typeVal a}
+ ~~~
+ *To C language*:
+ ~~~
+ struct {
+ typedef struct {
+ double val1;
+ double val2;
+ }type;
+ type typeVal;
+ double a;
+ }
+ ~~~
+
+- **Meta-Information**
+
+ *Type schema*:
+ ~~~
+ #Name=Value;
+ ~~~
+ *Example*:
+ ~~~
+ #a=hello;
+ ~~~
+
+- **Enumeration**
+
+ *Type schema*:
+ ~~~
+ #EnumName=value;E
+ ~~~
+ *Example*:
+ ~~~
+ #v1=0;#v2=1;E
+ ~~~
+ *To C language*:
+ ~~~
+ enum {
+ v1=0;
+ v2=1;
+ };
+ ~~~
+
+- **Method/Function**
+
+ *Type schema*:
+ ~~~
+ (Name)([Type]*)Type
+ ~~~
+ In order to represent the properties of function parameters (eg: in, out...), function parameters support the following metadata annotations:
+
+ |Meta-info|Description|
+ |---------|-----------|
+ |am=handle| void pointer for the handle|
+ |am=pre | output pointer with memory pre-allocated|
+ |am=out | output pointer, the caller should use `free` to release the memory|
+ |const=true| text argument(t) can use it, Normally a text argument will be handled as char*, meaning that the callee is expected to take of ownership.If a const=true annotation is used the text argument will be handled as a const char*, meaning that the caller keeps ownership of the string.|
+
+ *Example*:
+ ~~~
+ add(#am=handle;PDD#am=pre;*D)N
+ ~~~
+ *To C language*:
+ ~~~
+ int add(void* handle,double a, double b, double *ret);
+ ~~~
+ *Notes*
+
+ - For RPC interface, the return type of methods must be N, because remote service calls usually return error codes.
+ - Currently, the method only supports one output parameter, so the method cannot be defined in a multi-output parameter form.
+
+#### Interface Description File
+
+An interface description file is that the interface file written using the interface description language, and its file suffix is ".descriptor". Generally, to associate the remote service instance with the interface description file, the interface description filename should be consistent with the remote service name."
Review Comment:
```suggestion
An interface description file is that the interface file written using the interface description language, and its file suffix is ".descriptor". Generally, to associate the remote service instance with the interface description file, the interface description filename should be consistent with the remote service name.
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Improve doc (celix)
Posted by "PengZheng (via GitHub)" <gi...@apache.org>.
PengZheng commented on code in PR #690:
URL: https://github.com/apache/celix/pull/690#discussion_r1411638589
##########
bundles/remote_services/discovery_zeroconf/README.md:
##########
@@ -0,0 +1,73 @@
+---
+title: Discovery Zeroconf
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+## Discovery Zeroconf
+
+The `Discovery_zeroconf` is implemented based on [Bonjour](https://github.com/apple-oss-distributions/mDNSResponder), and its operation depends on the mDNS daemon.
+
+The mapping between celix and mdns services is as follows:
+
+| **mDNS service** | **celix service** |
+|------------------|-------------------------------------------|
+| instance name | service name+hash(endpoint uuid) |
+| service type | "_celix-rpc._udp"+${custom subtype} |
+| domain name | "local" |
+| txt record | service properties |
+| host | "celix_rpc_dumb_host.local."(It is dummy) |
+| port | 50009(It is dummy) |
+
+
+Because We will perform the mDNS query only using link-local multicast, so we set domain name default value "local".
+
+To reduce the operation of conversion between host name and address info. we set the address info to txt record, and set the host name and port to a dummy value("celix_rpc_dumb_host.local." and "50009").
+
+We set the instance name of the mDNS service as `service_name + hash(endpoint uuid)`. If there is a conflict in the instance name, mDNS_daemon will resolve it. Since the maximum size of the mDNS service instance name is 64 bytes, we take the hash of the endpoint uuid here, which also reduces the probability of instance name conflicts.
Review Comment:
Usage of UUID in instance name is explicitly discourage by RFC 6763:
>The default name should be short and
descriptive, and SHOULD NOT include the device's Media Access Control
(MAC) address, serial number, or any similar incomprehensible
hexadecimal string in an attempt to make the name globally unique.
The rational is explained [here](https://datatracker.ietf.org/doc/html/rfc6763#appendix-D).
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Improve doc (celix)
Posted by "PengZheng (via GitHub)" <gi...@apache.org>.
PengZheng commented on code in PR #690:
URL: https://github.com/apache/celix/pull/690#discussion_r1411638589
##########
bundles/remote_services/discovery_zeroconf/README.md:
##########
@@ -0,0 +1,73 @@
+---
+title: Discovery Zeroconf
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+## Discovery Zeroconf
+
+The `Discovery_zeroconf` is implemented based on [Bonjour](https://github.com/apple-oss-distributions/mDNSResponder), and its operation depends on the mDNS daemon.
+
+The mapping between celix and mdns services is as follows:
+
+| **mDNS service** | **celix service** |
+|------------------|-------------------------------------------|
+| instance name | service name+hash(endpoint uuid) |
+| service type | "_celix-rpc._udp"+${custom subtype} |
+| domain name | "local" |
+| txt record | service properties |
+| host | "celix_rpc_dumb_host.local."(It is dummy) |
+| port | 50009(It is dummy) |
+
+
+Because We will perform the mDNS query only using link-local multicast, so we set domain name default value "local".
+
+To reduce the operation of conversion between host name and address info. we set the address info to txt record, and set the host name and port to a dummy value("celix_rpc_dumb_host.local." and "50009").
+
+We set the instance name of the mDNS service as `service_name + hash(endpoint uuid)`. If there is a conflict in the instance name, mDNS_daemon will resolve it. Since the maximum size of the mDNS service instance name is 64 bytes, we take the hash of the endpoint uuid here, which also reduces the probability of instance name conflicts.
Review Comment:
Usage of UUID in instance name is explicitly discourage by RFC 6763:
>The default name should be short and
descriptive, and SHOULD NOT include the device's Media Access Control
(MAC) address, serial number, or any similar incomprehensible
hexadecimal string in an attempt to make the name globally unique.
The rational is explained [here](https://datatracker.ietf.org/doc/html/rfc6763#appendix-D).
Therefore, UUID should be removed from instance name altogether.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Improve doc (celix)
Posted by "PengZheng (via GitHub)" <gi...@apache.org>.
PengZheng commented on code in PR #690:
URL: https://github.com/apache/celix/pull/690#discussion_r1408606584
##########
libs/dfi/README.md:
##########
@@ -19,4 +19,243 @@ See the License for the specific language governing permissions and
limitations under the License.
-->
-# Apache Celix Dynamic Function Interface
+## Apache Celix Dynamic Function Interface
+
+Dynamic Function Interface (DFI) is a dynamic interface type implementation based on [libffi](https://en.wikipedia.org/wiki/Libffi).
+It can generate dynamic interface types according to the interface description file, and can convert the corresponding
+dynamic interface call into a [JSON representation](https://amdatu.atlassian.net/wiki/spaces/AMDATUDEV/pages/21954571/Amdatu+Remote#AmdatuRemote-AdminHTTP%2FJson). It can also convert the JSON representation into a dynamic interface call.
+
+### Conan Option
+ build_celix_dfi=True Default is False
+
+### CMake Option
+ CELIX_DFI=ON Default is ON
+
+### Interface Descriptor
+
+In `libdfi`, we have defined a set of simple interface description languages. Users can use this language to describe interface types, and at runtime, libdfi converts the interface description into a dynamic interface.
+
+Before introducing the interface description language, let's look at an example of interface description.
+
+~~~
+:header
+type=interface
+name=calculator
+version=1.0.0
+:annotations
+classname=org.example.Calculator
+:types
+StatsResult={DDD[D average min max input}
+:methods
+add(DD)D=add(#am=handle;PDD#am=pre;*D)N
+~~~
+
+As above, the interface description has four sections: the header section, annotations section, types section, and methods section. The format of each section is as follows:
+
+~~~
+ ':header\n' 'Name=Value\n'...
+ ':annotations\n' 'Name=Value\n'...
+ ':types\n' 'TypeId=Value\n'...
+ ':methods\n' 'MethodId=Value\n'...
+~~~
+
+Among them, the legal characters that can be used in the “name” and “TypeId” include [a-zA-Z0-9_], the legal characters in “MethodId” include [a-zA-Z0-9_] and ".();[{}/". Besides [a-zA-Z0-9], the legal characters in “value” also include ".<>{}[]?;:~!@#$%^&*()_+-=,./'". It's worth noting that there should not be spaces on either side of '=', and each statement must end with a newline(‘\n’).
+
+For the interface description, its header section must include three elements: type, name, version. The value of "type" should be "interface", "name" is the interface name (service name), the value of "version" should coincide with the version number in the actually used interface header file, and it should conform to [semantic versioning requirements](https://semver.org/).
+
+#### The Data Types In The Interface Descriptor
+
+The data types supported by the interface description include:
+
+- **Simple Types**
+
+ *Type schema*:
+
+ |**Identifier**|B |D |F |I |J |S |V |Z |b | i | j | s |P |t |N |
+ |---------|---|------|-----|-------|-------|-------|----|--------------|-----|--------|--------|--------|------|------|---|
+ |**Types**|char|double|float|int32_t|int64_t|int16_t|void|boolean(uint8)|uchar|uint32_t|uint64_t|uint16_t|void *|char *|int|
Review Comment:
Maybe we still need `char *` for plain `char *` and `t` for null-terminate c string.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Improve doc (celix)
Posted by "pnoltes (via GitHub)" <gi...@apache.org>.
pnoltes commented on PR #690:
URL: https://github.com/apache/celix/pull/690#issuecomment-1967655862
> Hi @pnoltes I have update this PR, it includes the following changes:
>
> 1. Add document for dynamic IP mechanism.
>
> 2. Add document for PR [Feature/dfi cleanup #699](https://github.com/apache/celix/pull/699) in libdfi README.md
Thanks, LGTM.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Improve doc (celix)
Posted by "PengZheng (via GitHub)" <gi...@apache.org>.
PengZheng commented on PR #690:
URL: https://github.com/apache/celix/pull/690#issuecomment-1835803033
I've finished reading RFC 6762 and 6763 (word by word), and have some further remarks on `discovery_zeroconf`:
## Large TXT Records
As previously pointed out by @pnoltes in a email:
> One of the issue we had with mDNS, is that payload size is very
limited and as result the remote service discovery was updated to a 2
step approach:
The current design adopt the approach sketched by [Service Instances with Multiple TXT Records
](https://datatracker.ietf.org/doc/html/rfc6763#autoid-20).
For this to work reliably, care must be taken to make sure that IP fragmentation does not happen, because
> Even on hosts that normally
handle Ethernet "Jumbo" packets and IP fragment reassembly, it is
becoming more common for these hosts to implement power-saving modes
where the main CPU goes to sleep and hands off packet reception tasks
to a more limited processor in the network interface hardware, which
may not support Ethernet "Jumbo" packets or IP fragment reassembly.
A snapshot of mDNS wireshark capture will be very helpful to illustrate the current approach.
From the current documentation (I have not checked the implementation), it is not clear how we deal with packet loss.
For service whose service advertisement fit in a single message, it is never a problem. But for services generating large TXT records, how do we guarantee to collect all associated TXT records?
## Fixed Hostname and Port in SRV
As mentioned above, this basically defeats the purpose of zeroconf. Don't do this!
Let just use the `hostname` of the OS.
For RSA over HTTP, port should be the real port listened by the HTTP server.
For RSA over shared memory, port could be 0.
It is OK to store URL in TXT records, but note that
> The target host name and TCP (or UDP) port number of the service are
given in the SRV record. This information -- target host name and
port number -- MUST NOT be duplicated using key/value attributes in
the TXT record.
URL/URI does not necessarily contain host and port. For more, check [URI Syntax Components](https://datatracker.ietf.org/doc/html/rfc3986#autoid-17).
## Service Instance Name and Service Subtypes
If the application use `rsa_shm` alone, then only service instances exported by `rsa_shm` should be discovered.
This is not the case (and less than ideal) for the current implementation: all service instances are enumerated by `discovery_zeroconf`. By using service subtypes, if the application only uses `rsa_shm`, `discovery_zeroconf` should search for something like `_shm._sub._celix-rpc._udp` rather than `_celix-rpc._udp`. For a user who want to list all exported services for debugging purpose, he/she can search for `_celix-rpc._udp`. Check [ Selective Instance Enumeration ](https://datatracker.ietf.org/doc/html/rfc6763#autoid-22) for more on service subtypes.
Service instance name is not used by RSA directly. It's mostly used for debugging.
We only need to provide a name informative enough, mDNSResponder will help to guarantee its uniqueness:
> The default name should be short and
descriptive, and SHOULD NOT include the device's Media Access Control
(MAC) address, serial number, or any similar incomprehensible
hexadecimal string in an attempt to make the name globally unique.
For discussion of why <Instance> names don't need to be (and SHOULD
NOT be) made unique at the factory, see [Appendix D](https://datatracker.ietf.org/doc/html/rfc6763#appendix-D), "Choice of
Factory-Default Names".
For it to be information, service name alone is not enough. I suggest we include pid of the service provider, which is very important for debugging a misbehaved remote service.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Improve doc (celix)
Posted by "xuzhenbao (via GitHub)" <gi...@apache.org>.
xuzhenbao commented on code in PR #690:
URL: https://github.com/apache/celix/pull/690#discussion_r1438973022
##########
bundles/remote_services/remote_service_admin_shm_v2/README.md:
##########
@@ -0,0 +1,86 @@
+---
+title: Remote Service Admin SHM
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+## Remote Service Admin SHM
+
+The Celix Remote Service Admin SHM bundle implement OSGi remote service using shared memory.
+In order to reuse the (de)serialization features of remote service admin,
+the remote service admin will be realized by ‘rsa_shm’ and 'rsa_json_rpc'(see [Remote Service Admin RPC Using JSON](../rsa_rpc_json/README.md)) bundles.
+The ‘rsa_shm’ bundle is used to realize ‘remote_service_admin_service_t’ and IPC.
+The ‘rsa_json_rpc’ bundle is used to realize (de)serialization and Creating service endpoint/proxy.
+
+### Supported Platform
+- Linux
+
+### Properties/Configuration
+
+| **Properties** | **Type** | **Description**|
+|----------------|----------|----------------|
+| **rsaShmPoolSize** | long | The RSA SHM pool size in bytes. Its value should be greater than 8192 bytes.(default 256KB) |
+| **rsaShmMsgTimeout** | long | The timeout of remote service invocation in seconds. (default 30s) |
+| **rsaShmCctIvNum** | long | The maximum concurrent invocations of the same service. If there are more concurrent invocations than its value, service invocation will fail.(default 32) |
Review Comment:
I have resolve it in #710
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Improve doc (celix)
Posted by "xuzhenbao (via GitHub)" <gi...@apache.org>.
xuzhenbao commented on code in PR #690:
URL: https://github.com/apache/celix/pull/690#discussion_r1438972675
##########
bundles/remote_services/remote_service_admin_shm_v2/README.md:
##########
@@ -0,0 +1,86 @@
+---
+title: Remote Service Admin SHM
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+## Remote Service Admin SHM
+
+The Celix Remote Service Admin SHM bundle implement OSGi remote service using shared memory.
+In order to reuse the (de)serialization features of remote service admin,
+the remote service admin will be realized by ‘rsa_shm’ and 'rsa_json_rpc'(see [Remote Service Admin RPC Using JSON](../rsa_rpc_json/README.md)) bundles.
+The ‘rsa_shm’ bundle is used to realize ‘remote_service_admin_service_t’ and IPC.
+The ‘rsa_json_rpc’ bundle is used to realize (de)serialization and Creating service endpoint/proxy.
+
+### Supported Platform
+- Linux
+
+### Properties/Configuration
+
+| **Properties** | **Type** | **Description**|
+|----------------|----------|----------------|
+| **rsaShmPoolSize** | long | The RSA SHM pool size in bytes. Its value should be greater than 8192 bytes.(default 256KB) |
Review Comment:
Here, we suggest that the value of RSA_SHM_POOL_SIZE should be greater than or equal to 8192 bytes, Because current memory pool ctrl block(control_t of [tlsf](https://github.com/apache/celix/tree/master/bundles/remote_services/remote_service_admin_shm_v2/shm_pool/src/tlsf)) size is 6536 bytes.
I've added a corresponding note to the documentation.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Improve doc (celix)
Posted by "PengZheng (via GitHub)" <gi...@apache.org>.
PengZheng commented on PR #690:
URL: https://github.com/apache/celix/pull/690#issuecomment-1958769418
Given that #710 has been merged, is this PR ready now? @xuzhenbao @pnoltes
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Improve doc (celix)
Posted by "xuzhenbao (via GitHub)" <gi...@apache.org>.
xuzhenbao commented on PR #690:
URL: https://github.com/apache/celix/pull/690#issuecomment-1958861737
> Given that #710 has been merged, is this PR ready now? @xuzhenbao @pnoltes Note that parts of #699 may need to be updated into this.
I will update this PR, please wait a few day.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Improve doc (celix)
Posted by "xuzhenbao (via GitHub)" <gi...@apache.org>.
xuzhenbao commented on PR #690:
URL: https://github.com/apache/celix/pull/690#issuecomment-1966022878
Hi @pnoltes
I have update this PR, it includes the following changes:
1. Add document for dynamic IP mechanism.
2. Add document for PR #699 in libdfi README.md
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org