DcclCodecGroups - GobySoft/goby GitHub Wiki

discussion for the blueprint https://blueprints.launchpad.net/dccl/+spec/dccl-codec-groups

Primary rationale: We want to improve the default codecs but preserve full backwards compatibility with version 2.

Add two new message level extensions that are ONLY valid in the root DCCL message: codec_group and codec_version. codec_version is an integer N that is identical to codec_group = "dccl.defaultN" used to indicate the default codec version the users want (currently either 2 or 3 for (Goby)-DCCL v2 or DCCL v3). If both are specified, codec_group takes precedence. The codec_group specified in the root message is inherited by child messages.

For example (this is similar to what's in dccl/test/dccl_codec_group)

message TestMsgGroup
{
  option (dccl.msg).id = 2;
  option (dccl.msg).max_bytes = 32;
  option (dccl.msg).codec_group = "test.grouptest";
  option (dccl.msg).codec_version = 3;

  optional double d = 1;
  repeated double d_repeat = 3 [(dccl.field).max_repeat=5];
  optional EmbeddedMsg1 msg = 2;

}

message EmbeddedMsg1
{
  optional double val = 1 [(dccl.field).min=0,
                           (dccl.field).max=100,
                           (dccl.field).precision=3];


  optional EmbeddedMsg2 msg = 2;
}

message EmbeddedMsg2
{
  optional double val = 1 [(dccl.field).min=0,
                           (dccl.field).max=100,
                           (dccl.field).precision=2];

}

dccl::Codec::info gives us (the codec is listed now to the right of the field size)

--------------------------- Header ---------------------------
dccl.id head...................................8
---------------------------- Body ----------------------------
TestMsgGroup...............................15-93 {test.grouptest}
        1. d..................................11 {test.grouptest}
        3. d_repeat[5]......................3-58 {test.grouptest}
        2. msg..............................1-24 {test.grouptest}
                1. val................................11 {test.grouptest}
                2. msg..............................1-12 {test.grouptest}
                        1. val................................11 {test.grouptest}

Resolution of which codec to use is in this order:

1. If (dccl.field).codec is explicitly set use that.
2. If this is an embedded message type and (dccl.msg).codec is explicitly set in that message definition, then use that.
3. If (dccl.msg).codec_group is set in the root message, use that.
4. If (dccl.msg).codec_version = N is set in the root message, use codec_group = "dccl.defaultN"
5. Use the (dccl.field).codec default (which is "dccl.default2").

For example:

message EmbeddedMsg1
{
  option (dccl.msg).codec="dccl.default3"; //overrides codec_group

  optional double val = 1 [(dccl.field).min=0,
                           (dccl.field).max=100,
                           (dccl.field).precision=3];


  optional EmbeddedMsg2 msg = 2;
}

message EmbeddedMsg2
{
  optional double val = 1 [(dccl.field).min=0,
                           (dccl.field).max=100,
                           (dccl.field).precision=2];

}


message TestMsgGroup
{
  option (dccl.msg).id = 2;
  option (dccl.msg).max_bytes = 32;
  option (dccl.msg).codec_group = "test.grouptest";
  option (dccl.msg).codec_version = 3;  // isn't used because codec_group is specified

  optional double d = 1 [(dccl.field).min=-100,
                         (dccl.field).max=126,
                         (dccl.field).precision=1,
                         (dccl.field).codec="dccl.default3"]; // overrides codec_group

  repeated double d_repeat = 3 [(dccl.field).max_repeat=5];
  optional EmbeddedMsg1 msg = 2;

}

gives

--------------------------- Header ---------------------------
dccl.id head...................................8
---------------------------- Body ----------------------------
TestMsgGroup...............................16-94 {test.grouptest}
        1. d..................................12 {dccl.default3}
        3. d_repeat[5]......................3-58 {test.grouptest}
        2. msg..............................1-24 {dccl.default3}
                1. val................................11 {test.grouptest}
                2. msg..............................1-12 {test.grouptest}
                        1. val................................11 {test.grouptest}