usage of oneof in protos

[pettaa123]

Hello, I really appreciate this project for its simplicity on the gRPC-device side. However, on the gRPC-LabVIEW side, we encounter cluttered code compared to the native LabVIEW implementation of the drivers. The primary reason for this is the extensive use of oneof in the driver’s proto files—nidaqmx.proto, for instance, contains 483 oneof statements. In LabVIEW, oneof generates classes, which feels unnecessarily heavy for an enum-like structure. LabVIEW users typically prefer to avoid class-based APIs, and I can't recall any official LabVIEW API that adopts such an approach.

I would like to understand whether there is an alternative to using oneof in cases like this. Additionally, could you explain why it is necessary to include all these _raw alternatives in the proto files?

  oneof pause_when_enum {
    Level1 pause_when = 9;
    int32 pause_when_raw = 10;
  }

[reckenro]

I'm not as familiar with the gRPC-LabVIEW side of things but I think there's an alternative for all of these oneofs. I haven't tried this personally but according to https://protobuf.dev/programming-guides/encoding/

Oneof fields are encoded the same as if the fields were not in a oneof. The rules that apply to oneofs are independent of how they are represented on the wire.

Alternative:
So what that means, I believe, is you can strip out the oneofs from your proto files by either choosing the Enum value or the raw value to keep with their same field number. So

Level1 pause_when = 9

remains in your .proto file in place of the enum and two fields and is used to generate your client stubs. Or you just use the int32 pause_when_raw = 10 field instead of the enum. Then after you build your client whichever field you chose would be sent over the wire and interpreted on the server side just fine.

Again, I haven't tried this but I think this would be the case if you want to make the adjustments on your .proto files you got from this repo.

gRPC-Device rationale for all the oneofs:
The enum values, for the most part, represent constants in the C API headers. We wanted to group these constants together into those enums and make them easy to use/reference for clients. We chose enums there because there isn't really a mapping of constants to anything else in protobuf/grpc. The reason for including the oneof / _raw fields is that most functions that would accept these groups of constants / grpc Enums could also accept arbitrary inputs so we couldn't just have the Enum we constructed from the constants as the field to pass forward to the C API. So we landed on using oneof's as a compromise to give the clients all the common constants used for a given input to a function but also allow them to get the full functionality of the method by allowing arbitrary input (that's what the _raw prefixed fields represent).

[pettaa123]

This is great feedback. I am not familiar with the C API. Are you aware of functions that can be used sanely with a set of constants and different non-constants? Or is it 'just' about passing e.g. ordinary integers instead of constants representing the same value?

[reckenro]

For the first question, I know a couple like in XNET there's a TimeOut enum that's

enum TimeOut {
  TIME_OUT_NONE = 0;
  TIME_OUT_INFINITE = -1;
}

So in the functions you can either use one of those constants for the timeout or any other number (I believe representing seconds):

oneof timeout_enum {
    TimeOut timeout = 6;
    double timeout_raw = 7;
  }

I don't have a good feel of the ratio of these types of functions to ones that lean more towards using true Enums where the only expected inputs are the collection of constants.

For your second question, yes you can just pass the ordinary integer values or (_raw) values instead of the constants representing those same values. So here using TimeOut.TIME_OUT_INFINITE is the same as passing the raw value -1 in. So effectively, you could always get by with just using the _raw values, though you may have some extra work client-side to keep track of the commonly used constants since you won't have the Enum values available anymore.

And an additional note, sometimes these constant collections / Enums represent non-integers like strings. The enum values in the proto will always be integers, but in those cases we will convert the integers to the proper type on the server side. These mappings can be found in the service.h file. So, for example, if you look at the TerminalName enum in XNET you'll see that it's all integers in the .proto definition. But on the server side, we'll take those enum values and translate them to strings like 1 -> "PXI_Trig0" and so on, defined on XNET's service.h file. All that being said, for these you could choose to pass along the _raw value or string in this case. This is just to give a breadcrumb to find the constant values you might use.

[pettaa123]

That were very helpful insights. I have to digest this now. Thank you so far.