[Gluster-devel] location hint table - requirements

[Anand V. Avati]

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 *path, void *value);

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

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

* Refer hint

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

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


* Finish refering hint 

  void forget_hint (hint_table_t *table, void * hint); [1]

  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

* Invalidate hint

  void invalidate_hint (hint_table_t *table, const char *path); [2]

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

  Another approach is to use update_hint with value as NULL.


 All of

1. update_hint
2. get_hint
3. forget_hint
4. invalidate_hint

can be called simultaneously by different threads on the same hint_table
 

[1]. For optimization, it can be enforced that every client of the
location hint manager should have a structure/pointer dedicated for the
use of hint  manager. This pointer can be used as a back-reference to
the container so that operations like forget_hint can happen without any
kind of searching.

[2]. 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)

-- 
Anand V. Avati