offset? seq? sequence?

[staltz]

To start a discussion on what these words mean and how should we use them, I'll write up how they are currently used in different modules:

In JITDB and ssb-db2

• offset: 0-based integer position of each item in the log as if the log were an array
• seq: number of bytes you have to go through in the log file to fetch a particular record
• sequence: 0-based integer position of each item in a feed as if the feed were an array, i.e. msg.value.sequence

In flumedb

• seq: an abstract monotonically increasing number without any semantics, semantics are defined case by case in the flumelog-* modules
• sequence: same as seq
• offset: in flumelog-offset, this is the number of bytes you have to go through in the log file to fetch a particular record, it's an implementation of the seq abstraction mentioned above, thus seq == offset

In async-flumelog

• offset: number of bytes you have to go through in the log file to fetch a particular record, example
• seq: same as offset, see this line and this line
• sequence: N/A

cc @arj03 @mixmix

[staltz]

And @cryptix what meanings do you assign for these words in go-ssb?

[cryptix]

what meanings do you assign for these words in go-ssb?

First of all, while the underlying implementation is an offset log, we skipped that concept on the upper layers, so we only speak of the sequence number of an entry. (Which also means that the numbers are much smaller and directly fit in bitmaps or dense arrays.)

To make it a bit less confusing I try to add context where ever I can, tho. So I dubbed the sequence of an entry in the offset file receive log sequence where as an entry on from a user is a feed sequence.

[staltz]

Thanks! So is this correct?

In go-ssb

• offset: (lower layer) number of bytes you have to go through in the log file to fetch a particular record
• "receive log sequence": (upper layer) 0-based integer position of each item in the log as if the log were an array
• "feed sequence": (upper layer) 0-based integer position of aech item in a feed as if the feed were an array

[cryptix]

Yes, exactly!

You never have to deal with offsets by hand. The details for how to get from rx sequence to the offset are hidden but explained in the docs for margaret/offset2.

[staltz]

I think it would be sensible to rename offset so that its meaning is "number of bytes to go through", that would make it consistent with flumedb, async-flumelog, go-ssb. It's a pain in the butt to do the rename, but it's only in jitdb and ssb-db2, and in the long run it will be better. I won't give this a high priority, but maybe it's good to be done still in December.

Would really appreciate written-down thoughts from @arj03 @mixmix @christianbundy

[mixmix]

I'm a big fan of consistency of language. I think it will save energy in the long run, so I'm an enthusiastic "yes please!" on your proposal

[arj03]

Agree with mix. I think we can and should fix this at least in the module we use in ssb-ngi-pointer js. And of course with these things, the sooner the better. I'm a bit afraid that the terminology would be different compared to ssb-db and maybe protocol guide. So maybe lets do it when ssb-db2 is really ready, meaning we have about and friends ready?

[staltz]

Good, I agree with the plan. I actually looked up the protocol guide when I created this issue and surprisingly the guide doesn't use these terms, I think I recall only sequence, I think there was no seq.

[staltz]

@arj03 I was thinking if we do this rename, it affects not only internal variable names, but also filenames, e.g. offset.index=>seqs.index, so it would be good to do it before putting into production (~ 5th January)

[arj03]

Hmm right :thinking:

[staltz]

I can dabble with a PR over glögi and gingerbread, and let's see how simple or complicated it turns out. Don't worry about it

[arj03]

Ohhhhhhhhhhhhhhh you have glög in Finland too? Aim for the Balmer peak :-)

[staltz]

Oh yes, the nordics are all basically the same. :) I love glögi

[mixmix]

What is this mysterious treat?

[arj03]

@mixmix you can see a recipe here. Basically a really strong drink, very good for the cold weather :)

[mixmix]

Woah bourbon! That's a spicy edge to the mulled wine I'm used to. Also cardomom is something I wouldn't have thought of but sounds delicious

[staltz]

Done