search

cognitect / transit-format

A data interchange format.
1.88k stars 36 forks source link

Please clarify caching explanation #34

Closed lgrapenthin closed 7 years ago

lgrapenthin commented 8 years ago

https://github.com/cognitect/transit-format#caching

  1. What does next id=42 mean? It appears out of context.
  2. "The first time a cacheable value is written, Transit adds an entry to to the cache map, increments the counter and writes the original value. If the counter wraps to 0..." How does the counter wrap? What is the purpose of the counter?

Thank you for this awesome piece of software.

dchelimsky commented 8 years ago

I can see what that section is confusing. I'll look into getting it updated (probably not before next week), but in the mean time ...

The counter is used to generate different cache codes for each cacheable element. The first one gets a cache code of "^0", the next one is "^1", etc, up to "^[[" (ascii rep of 44^2), after which it starts over at "^0".

next id=42 is just meant to represent the incrementing counter, but it's a confusing example.

lgrapenthin commented 8 years ago

Thanks for clarifying. One more question: "#tag, keyword and symbol values, and strings used as map keys are cached if they are longer than 3 characters." Does that mean strings are cached exclusively as map keys and the other mentioned types are always cached? Or only if they are used as map keys, too?

dchelimsky commented 8 years ago

Strings are only cached when they are map keys (and all keys in the map are "string-able"). The other types are always cached.

I believe the rationale here is that we want to cache things that are likely to appear more than once. tags, keywords, and symbols generally carry some semantic or a reference to a specific thing, and are therefore likely to reappear. Strings as map keys are likely to reoccur if there is a collection of maps. Strings that are not map keys, who knows? Make sense?

lgrapenthin commented 8 years ago

Yeah, that makes sense. Thanks for clarifying.

rauhs commented 7 years ago

I'd also like to vote for clarification. Again

tag, keyword and symbol values, and strings used as map keys are cached if they are longer than 3 characters.

is not clear. I only realized the behavior by trying it out. This is important when designing the API.

dchelimsky commented 7 years ago

Well, this issue gives new meaning to "(probably not before next week)" in my first comment! I will pursue getting this addressed today!

dchelimsky commented 7 years ago

I updated the Caching section of the README. Please let me know if anything is still unclear.