> -----Original Message-----
> From: C. Michael Pilato [mailto:cmpilato_at_collab.net]
> Sent: vrijdag 13 augustus 2010 18:40
> To: Subversion Development
> Subject: Confusing svn_log_entry_t docstrings.
>
> Can someone help me make sense of some of our public docstrings? I'm
> looking at the svn_log_entry_t structure, and I see the following:
>
>
> typedef struct svn_log_entry_t
> {
> /** A hash containing as keys every path committed in @a revision;
> the
> * values are (#svn_log_changed_path_t *) stuctures.
> *
> * The subversion core libraries will always set this field to the
> same
> * value as changed_paths2 for compatibity reasons.
> *
> * @deprecated Provided for backward compatibility with the 1.5 API.
> */
> apr_hash_t *changed_paths;
>
> [...]
>
> /** A hash containing as keys every path committed in @a revision;
> the
> * values are (#svn_log_changed_path2_t *) stuctures.
> *
> * If this value is not @c NULL, it MUST have the same value as
> * changed_paths or svn_log_entry_dup() will not create an identical
> copy.
> *
> * The subversion core libraries will always set this field to the
> same
> * value as changed_paths for compatibity with users assuming an
> older
> * version.
> *
> * @since New in 1.6.
> */
> apr_hash_t *changed_paths2;
>
>
> 'changed_paths2' says that it is a "hash containing as keys every path
> committed in @a revision; the values are (#svn_log_changed_path2_t *)
> stuctures" and that "If this value is not @c NULL, it MUST have the
> same
> value as changed_paths."
>
> But 'changed_paths' says that it is a "hash containing as keys every
> path
> committed in @a revision; the values are (#svn_log_changed_path_t *)
> stuctures."
>
> How in the world can 'changed_paths2' and 'changed_paths' have the same
> value while managing to point to hashes with two different value types?
> What am I missing?
svn_log_changed_path2_t is defined as a structure starting with the exact same definition as svn_log_changed_path_t. So any svn_log_changed_path2_t instance can be seen as a svn_log_changed_path_t, but you miss some fields that way.
The problem is that we never created create and duplicate functions for svn_log_changed_path_t, so it was impossible to add new fields. So we revved the structure (and the hash containing it) to pass the new data instead. But you can safely pass the new value as the old value, but not the other way around.
(The only other option to provide more per path data was to rev every log function inside the fs, ra and client layer)
As we never consume these structures, we can define (like that doctag says), that you always get the same hash pointer if the second hash pointer is available. (We just create the new hash and that value happens to be valid as the old hash)
We have had a similar construct in svn_io_* for years, where we passed a svn_node_kind* as value from a hash, then some struct and then later a larger struct.. but you always get the same pointers, because the layout matches.
Bert
Received on 2010-08-13 19:06:29 CEST