Here are the formal requirements (expressed as API) from location hint
table (manager)

* Create a new hint table

  hint_table_t * create_new_hint_table (int size);

  creates a new hint table, initializes and optimizes  its operation and
  makes it usable from the very next call.

  size is the number of hints the table can remember.


* Update hint

  update_hint (hint_table_t *table, const char *key, void *value);

  makes the hint_table learn about the new knowledge that 'path' is
  associated with 'value'.

  if key is already existing, gracefully destroy the value and insert
  new value

  if key is not existing, use an empty slot for storing key and value

  Salvaging -
      If all hint slots are storing hints, lookup a hint which was refered
      for oldest, and not still  being  referred.

      If all slots are still being referred, do not learn the new knowledge.

      From the slot chosen for re-use, the old key and value should be 
      destroyed gracefully

  Threading issues - Consider
  1. somebody refering old value while updating key with new value
  2. somebody forgeting while updating
  3. somebody invalidating while updating


* Refer hint

  void * get_hint (hint_table_t *table, const char *key);

  helps the caller by giving a hint, and makes a note that the caller is
  using the hint knowledge

  Threading issues - Consider
  1. somebody updating while refering [which involves salvaging old unreferred entries]
  2. somebody forgetting while referring
  3. somebody invalidating while refrring


* Finish refering hint 

  void forget_hint (hint_table_t *table, void * key);

  Tell the hint manager that this hint  is no more used by you, so that
  it aids its decision of reusing this slot for new hint updation.

  When there are nobody refering to the hint, the slot should be marked free
  and the key/value should be destroyed gracefully.

  Threading issues - Consider
  1. somebody updated value between  get_hint and forget_hint
  2. seombody referring while forgetting
  3. somebody invalidating while forgetting


* Invalidate hint

  void invalidate_hint (hint_table_t *table, const char *key);

  Tell the hint manager that this hint is no more valid (example the
  file got deleted).

  The hints may already be being referred by another client. The slot
  should still be reserved but should not be freshly refereable (by
  get_hint)

  The client is expected to call forget_hint. When there are nobody
  refering to the hint, the slot will be marked free and key/value be 
  destroyed.

  Another API approach is to use update_hint with value as NULL.

  Threading issues - Consider
  1. somebody updating while invalidating [maybe trying to update same entry]
  2. somebody referring while invalidating
  3. somebody forgetting while invalidating