putAttribute vs. setAttribute

[yurishkuro]

I am just curious if there was some consideration behind the put name, and if so to document it here.

[SergeyKanzhelev]

my understanding was always that set has a semantics of first and only write. put is used as "create or overwrite". But I never put much thoughts into it. So worth discussing.

Is it set in OT?

[bogdandrutu]

I think this is very language specific. In Java we went with the "map" terminology of put, and it has the same semantics.

[yurishkuro]

@SergeyKanzhelev yes, it's SetTag/setTag/set_tag in OT Go/Java/Python

@bogdandrutu are you saying the name would change in a different language? That will probably be rather confusing.

[SergeyKanzhelev]

I'm fine either way

[bogdandrutu]

@yurishkuro If we want to have generic names I am fine with that, though some java devs will get confused about terminology.

One option is to use standard terminology for all these "map" like operations (we use this in tags in golang):

• insert - If k already exists, doesn't update the value.
• update - If k doesn't exists, doesn't insert the value.
• upsert - It inserts the value if k doesn't exist already, it updates the value if k already exists.
• delete - deletes the value associated with keys.

[yurishkuro]

I prefer not over to complicate things. set is similar to classic setters, the upsert semantics of it seems universal. While put is very Java-centric, many other languages don't have an equivalent.

The one caveat from OT is that SetTag() had unspecified behavior if called more than once with the same key. This wasn't related to set vs put, more to the implementation and efficiency (e.g. Jaeger keeps KVs in array, rather than a map, so guaranteeing uniqueness would actually be extra work). There was never a particularly strong use case for the multi-map semantic.

[bogdandrutu]

I agree that the implementation can keep everything in an array, but when exported to you dedup?

[yurishkuro]

You can, but it's still extra CPU cycles and memory allocations that become necessary if the API semantics require key uniqueness.

[bogdandrutu]

Then we should say that attributes is a List<Pair<Key, Value>>, so a better name is "addAttribute" probably.

[carlosalberto]

I prefer not over to complicate things. set is similar to classic setters, the upsert semantics of it seems universal. While put is very Java-centric, many other languages don't have an equivalent.

I agree on this one - I think we can either go with addAttribute or setAttribute, even if it's not so Java centric.

[bogdandrutu]

Decision: setAttributes, the behavior is a List of attributes and if the backend dedups then the ordering should be guaranteed.