Thank you Kay for the feedback.
I have to think a while how to re-format the text accordingly, not there yet but I have some kind of an idea.
I have also struggled a lot with the “Field” vs “PVField” issue, no matter how many times I have read the examples and tried things out, I still get confused with what is what.
What you write clarifies the thing a lot to me; I was always wondering if all the steps were really needed. And what would I do with the empty description;
I could not figure out an easy way to figure out the structure from the description (what elements are there; well, with a NType you roughly know what to expect but still) so the point was kind of lost to me.
I guess that a similar rewrite will also happen for the C++ code and if I skip or reduce the text about introspection, a similar pattern will apply for both C++ and Java?
(i.e., only the step 4 in your example below will be implemented.)
I hope the text will be useful for somebody else, for myself I am just trying to follow the Feynman method [1].
Timo
- https://golden.com/wiki/Feynman_Technique
I do worry about the 'introspection'. It's confusing, it's part of what makes the currend C++ API so hard, and most important it's hardly necessary.
PVData currently distinguishes between "Field" and "PVField", between the plain description of a structure and an actual container that holds data.
"type double" vs. "double 3.14".
The examples are full of two-step code that first creates the description, then the structure, with two copies of each, one using a "builder" and the other not using
a "builder".
In reality, you almost always need the actual container:
·
You want to serve data, so you fill the data container
·
You read data, so you get the container.
OK, in the first step of the read protocol you get the description of the data, but then in the next step you need to fill that with data, so you do create the container right away.
·
You monitor data, so you apply received changes from a 'small' container to the 'full' container that caches the complete structure.
The only example where you just need the description is the "pvinfo" command, where you never fill it with data.
With the new PVA java client and server, I've only implemented the container. The PVAxxx classes all hold data. When you read, i the first step you get the container
where the double value = NaN, an array is empty, .., i.e. you get an empty container, but you do get the container which is then filled with data one millisecond later.
OK, for the plain PVInfo command the container remains empty, the values are all 0, NaN, null, empty.
==> This has cut the amount of code in half, maybe even into just 25% because instead of
1) methods for field description,
2) builder for field description,
I only have the builder for data, which in the pvinfo case is never populated with data
---> Much easier to understand, less code to maintain, works just fine.
So in the description, I would not talk too much about the not really necessary distinction between Field and PVField. That's just a side effect of the current implementation
that makes it more confusing.
Dear core developers,
I have to keep explaining PVA concepts to my colleagues over and over. To help myself in the task, I wrote a short piece of text where I tried to summarize the concepts of pvData.
I picked up and edited pieces from different sources, mainly from the V4 website documents (Marty et al) and added some text of my own.
Please take a look here:
https://docs.epics-controls.org/en/latest/guides/OverviewOfpvData.html
It is not yet linked from the top menu that Ralph created in the Documentathon. Before doing that I would ask you to check:
-if the text is factually correct or have I misunderstood something,
-is it complete enough (i.e., have I missed something essential),
-is the amount of detail appropriate; I intentionally reduced the amount of detail, to highlight the concepts in a concise way
-any other suggestions and corrections (grammar, style) are also most welcome.
And also let me know if this has enough value to be added into the introductory documentation.
Timo