Discuss and document usage scenarios

[ernestum]

With modern embedded compilers being able to translate C++ the rule saying embedded -> use C89 is not as strict any more. Therefore it is time to rethink what usage scenarios we would like to support and what scenarios we decide to ignore. I recorded the current state below with some comments on what scenarios we might like to support and what scenarios we might like to drop (to save work).

Even if the result of this discussion is just "we leave it like this", it belongs to the documentation so potential users can quickly asses if they want to use ZCM for their software project.

Possible scenarios:

API	target	transport type		currently supported	support needed
C89	embedded	blocking		no	only with RTOS
C89	embedded	non-blocking		yes	yes
C89	PC	blocking		yes (internally uses C++)	? (why if C++ support is needed anyways to compile)
C89	PC	non-blocking		yes	yes
C++	embedded	blocking		no	only with RTOS
C++	embedded	non-blocking		yes	yes
C++	PC	blocking		yes	yes
C++	PC	non-blocking		yes	yes

I would love to hear your opinions!

[olsoni]

Agreed, a clear document like this is a great idea. Couple of points on your proposed list :

I believe the thought behind originally doing the C89 PC support (using internal C++) was that even if someone wanted to use the C89 API, it was very unlikely that they would be unable to compile the C++ internals for their system. The main reason we saw for wanting the C89 api anyway was for ease of generating bindings in other languages. I'm not opposed to reexamining that assumption, but that was where we were coming from, especially if you see some distinct use cases where it would make a difference.

C++ embedded is actually supported for nonblocking use cases. We currently use it on a TIVA microprocessor, that's where the TIVA transport options came from in the third-party transports sub-repo.

[ernestum]

I see so you just initialize the zcm member variable "by hand" without a constructor? When you use the C++ interface on embedded?

[olsoni]

Not quite, we just use the transport pointer constructor:

zcmUsb = new zcm::ZCM(zcm_trans_tiva_usb_create(...));

[jbendes]

so here's the bit of a tricky thing, zcm currently supports all of these use cases. The ZCM_EMBEDDED was simply intended to be a switch saying use only C89 compliant code and minimize dynamic memory usage. We can rename that #define, but the goal of it was never to tell developers that they cant use the blocking transport on embedded systems. I really like your chart and think it would be a great idea to add that to the documentation, but I would change it to be examples in the final column of how people would use it. Thoughts?

[ernestum]

@olsoni oh I just missed the third constructor ... sorry

@jbendes I am not too deep in embedded developement. As far as I know the blocking transports need multi-threading support. Are there embedded platforms that provide the same threading API that you use?

I think it is a good idea to add this chart to the documentation. Maybe we can collect usage examples here? I will try to make some up later but it might be good to have more diversity in the examples and not only my perspective.

[jbendes]

No you're totally right. I confused myself before. The blocking API is only for POSIX systems. The nonblocking API needs no OS. I like your diagram. We should definitely add it or something like it to the docs. Would be very helpful for clarifying all the use cases. @olsoni and I were discussing putting together a page of actual use cases as well. That could also be interesting to show the real-world range of uses zcm is a part of