DcclCodecGroups

Toby Schneider edited this page May 26, 2016 · 2 revisions

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}
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.