Re: [PATCH 00/22] cache cursors: an introduction

From: Chuck Lever <cel@citi.umich.edu>
Date: Sep 12, 2005, 16:37 UTC
Message-ID: <4325AED6.8050401@citi.umich.edu>
In-Reply-To: <4325A0D9.2000806@gmail.com>

A Large Angry SCM wrote:

> Since you are proposing an API, some basic documentation about how to 
> use the API would be nice. Comments in cache.h seems the best place, for 
> now.

actually it might be best to have a list discussion first. if i can answer questions and provide a few explanations here, the list archive might be a reasonable resting place for documentation.

the API is fairly simple and is documented via the function names. there isn't a whole lot of function-level documentation in the git code base that i have seen, so i erred on the side of less is more.

the first patch "introduce-cache-cursors provides most of the interface, and the subsequent patches demonstrate how to use it by changing parts of the git C code base to use the interface instead.

the main pieces are:

+  struct cache_cursor

which describes a position in the cache.

+  init_cc

which sets the given cursor to the top of the cache.

+  cc_to_ce

which extracts the cache entry that a cursor refers to.

+  next_cc, prev_cc, cache_eof

which allow cursor movement.

+  next_name

which skips to the next unique name in the cache.

+  walk_cache

which calls a function for each entry in the cache, in order. the given function is responsible for moving the cursor to the next position before returning.

+  cache_find_name

which returns a cache cursor pointing to the found entry or to the entry which can be used as an insertion point if nothing matches.

+  cache_find_entry

which is a wrapper around cache_find_name that returns an entry instead of a position.

> The sentence "This patch series is against the "proposed updates" 
> branch, as of a couple of days ago." should have also included a commit 
> ID. That way we would know where/when the patches would apply cleanly 
> for testing and dissection.

i'm a dork.

6ae3d6e6d0f87cfa75b4bf213a485ff687defce8

i will include the base ref in my future postings.

begin:vcard fn:Chuck Lever n:Lever;Charles org:Network Appliance, Incorporated;Linux NFS Client Development adr:535 West William Street, Suite 3100;;Center for Information Technology Integration;Ann Arbor;MI;48103-4943;USA email;internet:cel@citi.umich.edu title:Member of Technical Staff tel;work:+1 734 763 4415 tel;fax:+1 734 763 4434 tel;home:+1 734 668 1089 x-mozilla-html:FALSE url:http://www.monkey.org/~cel/ version:2.1 end:vcard