# 10/03 Report: `ara::com` (from on service side)
reference: `AUTOSAR_EXP_ARAComAPI`, CanNm repo

## `ara::com` approach: Proxy Skeleton Pattern

### About Service
> Service Skeleton: This code is - from the perspective of the service implementation, which provides functionalities according to the service definition - the code, which allows to **connect the service implementation to the Communication Management transport layer, so that the service implementation can be contacted by distributed service consumers**.
>
> In an object-oriented language binding, this typically is an instance of a generated class. Usually the service implementation from the application developer is connected with this generated class via a **subclass relationship**.
So the service side application code interacts with this middleware adapter either by **implementing abstract methods of the generated class or by calling methods of that generated class**.
> [AUTOSAR_EXP_ARAComAPI 5.1]

## data types in `ara::com` and the header `ara/com/types.h`
More investigation on AP data type is necessary.
(What are provided, where are the data types defined, etc.)

> For most of the types `ara::com` provides a default mapping to existing C++ types in `ara/com/types.h`. This default mapping decision could be reused by an AP product vendor.
> [AUTOSAR_EXP_ARAComAPI 5.3]

### Specification of `ara/com/types.h`
See `AUTOSAR_SWS_CommunicationManagement` 8.1.1.3

## Skeleton (service side parent class)
See codes in `AUTOSAR_EXP_ARAComAPI Listing 6.16`

### Example of a service initialization and offering (`AUTOSAR_EXP_ARAComAPI Listing 6.15`)

using namespace ara::com;
/**
* Our implementation of the RadarService -
* subclass of RadarServiceSkeleton
*/
class RadarServiceImpl;
int main(int argc, char** argv) {
    // read instanceId from commandline
    ara::core::string_view instanceIdStr(argv[1]);
    RadarServiceImpl myRadarService(InstanceIdentifier(instanceIdStr));
    // do some service specific initialization here ....
    myRadarService.init();
    // now service instance is ready -> make it visible/available
    myRadarService.OfferService();
    // go into some wait state in main thread - waiting for AppExecMgr
    // signals or the like ....
    return 0;
}

From the example, we can see that the init and offer are probably done by other codes, rather than the subclass of the service.
(I didn't see any description of how a service instance is instantiated by AUTOSAR, we need more investigation on how an **ara service** is instantiated.)

### About `MethodCallProcessingMode` (second arg in skeleton constructors)
`MethodCallProcessingMode` specifies how CM will interact with a service.
#### Polling (`kPoll`)
> ... Here the application developer on the service provider side explicitly calls an ara::com provided API to process explicitly **one** call event.
> [AUTOSAR_EXP_ARAComAPI 6.3.3]

> If you set it to `kPoll`, the Communication Management implementation will not call any of the provided service methods asynchronously!
> If you want to process the next (assume that there is a queue behind the scenes, where incoming service method calls are stored) pending service-call, you have to call the following method on your service instance:
> ```cpp
> /**
> * ...
> * Only available in polling mode.
> */
> ara::core::Future<bool> ProcessNextMethodCall();
> ```
> [AUTOSAR_EXP_ARAComAPI 6.3.3.1]

An use case is also given:
> A simple use case for a typical RT application could be:
> - RT application gets scheduled.
> - it calls `ProcessNextMethodCall` and registers a callback with `ara::core::Future::then()`
> - the callback is invoked after the service method called by the middleware corresponding to the outstanding request has finished.
> - in the callback the RT application decides, if there is enough time left for serving a subsequent service method. If so, it calls another `ProcessNextMethodCall`.
> [AUTOSAR_EXP_ARAComAPI 6.3.3.1]

From the explanations and example use case above, I think that from a service perspective, this is what will happen:
- Service calls `ProcessNextMethodCall` so CM knows we're accepting request
- CM delivers the request to the method and we process the request
- After we finished the request (maybe returning from the method?), CM calls the callback provided with `ProcessNextMethodCall`
- In the callback, we decide whether to call `ProcessNextMethodCall` again

Also, from the quote *"will not call any of the provided service methods asynchronously!"* may we conclude that when a method is running, other methods won't be called? Because conceptionally, the caller should block after a synchronous call.

(The above two points are not provided in the EXP document)

#### Event-driven (`kEvent`, `kEventSingleThread`)
> Communication Management implementation will dispatch events asynchronously to the service method implementations at the time the service call from the service consumer comes in.
>
> Opposed to the `kPoll` mode, here the service consumer implicitly controls/triggers service provider process activations with their method calls!
> .....
> That means for our example: If — at the same point in time — one call to method `Calibrate` and two calls to method `Adjust` arrive from different service consumers, the Communication Management implementation is allowed to take three threads from its internal thread-pool and do those three calls for the two service methods concurrently.
> On the contrary the mode `kEventSingleThread` assures, that on the service instance only one service method at a time will be called by the Communication Management implementation.
> [AUTOSAR_EXP_ARAComAPI 6.3.3.2]

This mode seems to be more straightforward, CM just calls the method. In `kEvent` mode, the calls may be concurrent, while in `kEventSingleThread` mode, only one method will be called at a time.

Here I think that in `kEventSingleThread` mode, even though the method calls don't happen at the exact same time, the calls can still overlap. Since the events are dispatched asynchronously.
(But again, the point above is not provided in the EXP document)

## Future tasks & questions

### Questions
- verify the behavior of CM, if possible
- the skeleton class is generated, can it be done in Simulink?
- how is an ara service instantiated? (like Nm)
- the configurations (like nMNetworkTimeout, nmWaitBus SleepTime) comes from the manifest, how do we get that? Read the manifest file? Or it will be a class or something?

### Conclude & Future
- Nm can be tested without CM and SM. We can just fake the CM calls and examine the behavior of NM
- `ara/com/types.h`, `AUTOSAR_SWS_CommunicationManagement` 8.1.1.3
- translate the requirement and specification into tests
- try to somehow generate the skeleton class