Finalize generated Go API

[tigrannajaryan]

The API currently looks like this:

Struct

// Return value of “Field” of primitive type
S.Field() <type>

// Return pointer to “Field” of non-primitive type
// For dict-enabled types returned value is readonly.
S.Field() *<type>

// Set value of “Field” of primitive type
// For optional fields also sets the presence flag
S.SetField(val <type>)

// Set value of “Field” of dict-enabled non-primitive type
// For optional fields also sets the presence flag
S.SetField(val *<type>)

// Check if an optional “Field” is present
S.HasField() bool

// Unset presence flag for an optional “Field”
S.UnsetField()

Oneof

// Return the type of the current choice in oneof
S.Type() <int-type>

// Return value of primitive type, assuming the current choice
// of oneof is “Field”.
S.Field() <type>

// Return pointer to non-primitive type, assuming the current choice
// of oneof is “Field”.
// For dict-enabled types returned value is readonly.
S.Field() *<type>

// Set value of primitive type. Sets the choice of oneof to “Field”
// For optional fields also sets the presence flag
S.SetField(val <type>)

// Set value of dict-enabled non-primitive type by pointer.
// Sets the choice of oneof to “Field”
S.SetField(val *<type>)

Array

// Return number of elements
A.Len()

// Return element at index i (primitive type).
// Panics if index is out of range.
A.At(i int) <type>

// Set element at index i (primitive type)
// Panics if index is out of range.
A.SetAt(i int, val <type>)

// Return element at index i (non-primitive type)
// Panics if index is out of range.
// For dict-enabled types returned value is readonly.
A.At(i) *<type>

// Set element at index i (dict-enabled, non-primitive type)
// Panics if index is out of range.
A.SetAt(i int, val *<type>)

// Set length of the array. If array length grows, new elements
// are appended at the end in a zero-initialized state.
// For non-primitive types subsequent At() for new elements returns non-nil pointer.
A.EnsureLen(len int)

Multimap

// Return number of key-value pairs
M.Len()

// Return key-value pair at index i
M.At(i int) *<KeyValueType>

// Return key of the pair. Returns a pointer for non-primitive types.
<KeyValueType>.Key() <type>

// Return value of the pair. Returns a pointer for non-primitive types.
<KeyValueType>.Value() <type>

// Set the key of the pair (primitive type)
<KeyValueType>.SetKey(key <type>)

// Set the key of the pair (dict-enabled non-primitive type).
<KeyValueType>.SetKey(key *<type>)

// Set the value of the pair (primitive type)
<KeyValueType>.SetValue(key <type>)

// Set the value of the pair (dict-enabled non-primitive type).
<KeyValueType>.SetValue(key *<type>)

// Set length of the multimap. If the length grows, new key-value pairs
// are appended at the end in a zero-initialized state.
// For non-primitive types subsequent At() for new key-value pairs return
// non-nil pointer.
M.EnsureLen(len int)

We want to review and decide if this is the desirable API or we want to change it.

[tigrannajaryan]

I did some benchmarking of 2 approaches for multimap methods: one with direct KeyAt()/ValueAt() methods, the other with At() returning an accessor which has Key()/Value() methods.

Getters end up working exactly at the same speed since Go optimizer inlines all methods and then correctly figures out accessor can be elided, so the final generated machine code is equivalent. Unfortunately Setters are much slower with accessor pattern, since the generated code ends up being too complex and the inliner gives up. The setter that uses an accessor runs 5 times slower (on the fast path) than the one without (0.5ns vs 2.5ns).

I am going to change the API to just have Key/SetKey/Value/SetValue methods directly on the multimap since 5x slower is not acceptable to me. So instead of m.At(i).Key() we will have m.Key(i).

We will have the following:

// Return number of key-value pairs
M.Len()

// Return key at index i. Returns a pointer for non-primitive types.
M.Key(i int) <type>

// Return value at index i. Returns a pointer for non-primitive types.
M.Value(i int) <type>

// Set the key at index i (primitive type)
M.SetKey(i int, key <type>)

// Set the key at index i (dict-enabled non-primitive type).
M.SetKey(i int, key *<type>)

// Set the value at index i (primitive type)
M.SetValue(i int, key <type>)

// Set the value at index i (dict-enabled non-primitive type).
M.SetValue(i int, key *<type>)

// Set length of the multimap. If the length grows, new key-value pairs
// are appended at the end in a zero-initialized state.
// For non-primitive types subsequent At() for new key-value pairs return
// non-nil pointer.
M.EnsureLen(len int)