Subject: Re: [PATCH] refs: document transaction semantics

From: David Turner <[email-masked]>
Date: Thu, 25 Feb 2016 15:10:13 -0500

I thought it would be better in the api docs, since it's a design
decision that all backends should follow.

On Thu, 2016-02-25 at 15:05 -0500, David Turner wrote:
> Add some comments on ref transaction semantics to refs.h
> 
> Signed-off-by: David Turner <[email-masked]>
> ---
>  refs.h | 12 ++++++++++++
>  1 file changed, 12 insertions(+)
> 
> diff --git a/refs.h b/refs.h
> index c0964f5..9b3eaf3 100644
> --- a/refs.h
> +++ b/refs.h
> @@ -112,6 +112,11 @@ extern int dwim_log(const char *str, int len,
> unsigned char *sha1, char **ref);
>   *   If this succeeds, the ref updates will have taken place and
>   *   the transaction cannot be rolled back.
>   *
> + * - Instead of `ref_transaction_commit`, use
> + *   `initial_ref_transaction_commit()` if the ref database is known
> + *   to be empty (e.g. during clone).  This is likely to be much
> + *   faster.
> + *
>   * - At any time call `ref_transaction_free()` to discard the
>   *   transaction and free associated resources.  In particular,
>   *   this rolls back the transaction if it has not been
> @@ -127,6 +132,13 @@ extern int dwim_log(const char *str, int len,
> unsigned char *sha1, char **ref);
>   *
>   * The message is appended to err without first clearing err.
>   * err will not be '\n' terminated.
> + *
> + * Caveats
> + * -------
> + *
> + * Note that no locks are taken, and no refs are read, until
> + * `ref_transaction_commit` is called.  So `ref_transaction_verify`
> + * won't report a verification failure until the commit is
> attempted.
>   */
>  struct ref_transaction;
>