[PATCH 0/5] promise: introduce promises to track success or error

["Philip Peterson via GitGitGadget" <gitgitgadget@gmail.com>]

Hello all, this is my first patchset so thank you for being patient with me
as I learn the process and conventions of your very fine project. These
patches are intended as part of the Libification effort, to show how we
could use a Promise structure to help return values from functions.


Problems
========

We seek to make libification easier by establishing a pattern for tracking
whether a function errored in a rich way. Currently, any given function
could immediately die(), or use error() to print directly to the console,
bypassing any relevant verbosity checks. The use of die() currently makes
use of Git as a library inconvenient since it is not graceful.

Additionally, returning using return error(...) (as is commonly done) always
just returns a generic error value, -1, which provides little information.


Approach
========

I solve this problem by splitting the single return value into two return
values: error, and message. However, managing two output variables can
require some coordination, and this coordination can be abstracted away by
use of an existing pattern named Promise.


Promise Concept
===============

A promise is a contract representing "some task" that will eventually
complete. Initially a promise is considered in a pending state. When it
completes, one of two codepaths will eventually be entered: reject, or
resolve. Once resolved or rejected, the promise enters a different state
representing the result. Reject or resolve may only be called once on a
given promise.

Until now, everything I described up to this point is consistent with other
implementations, such as the ECMAScript standard for promises. However, this
implementation departs from the complexity of those promises. In this
implementation, promises are simple and canNOT be chained using .then(...)
and do NOT have any notion of automatic bubbling (via re-entering the
pending state).


Sample output and reproduction
==============================

During an error, we can have richer feedback as to what caused the problem.

% git apply garbage.patch
error: 
    could not find header
caused by:
    patch fragment without header at line 1: @@ -2 +2 @@


To reproduce this output, you can use the following patch (garbage.patch):

@@ -2 +2 @@



Goals
=====

I would love to get feedback on this approach. This patchset is kept small,
so as to serve as a minimal proof of concept. It is intended to abstract to
asynchronous use-cases even though this is only a synchronous one.
Eventually, any top-level function, such as apply_all_patches(...) would
return its output via a promise to make the library interface as clean as
possible, but this patchset does not accomplish this goal. Hopefully it can
provide a direction to go in to achieve that.


Diversion
=========

While building this patchset, I noted a bug that may not have a concrete
repro case in the master branch. The bug is that when invoking git am, it
can call out to git apply, passing many flags but interestingly not the
--quiet flag. I included a fix for this issue in the patchset.


Potential Issue
===============

There is one difficulty with this approach, which is the high level of
repetition in the code required. Tracking which promise is which is its own
source of complexity and may make mistakes more prone to happen. If anyone
has suggestions for how to make the code cleaner, I would love to hear.

Thank you, Philip

Philip Peterson (5):
  promise: add promise pattern to track success/error from operations
  apply: use new promise structures in git-apply logic as a proving
    ground
  apply: update t4012 test suite
  apply: pass through quiet flag to fix t4150
  am: update test t4254 by adding the new error text

 Makefile               |   1 +
 apply.c                | 133 +++++++++++++++++++++++++++--------------
 apply.h                |   9 ++-
 builtin/am.c           |   5 ++
 promise.c              |  89 +++++++++++++++++++++++++++
 promise.h              |  71 ++++++++++++++++++++++
 range-diff.c           |  14 +++--
 t/t4012-diff-binary.sh |   4 +-
 t/t4254-am-corrupt.sh  |   9 ++-
 9 files changed, 279 insertions(+), 56 deletions(-)
 create mode 100644 promise.c
 create mode 100644 promise.h


base-commit: 2996f11c1d11ab68823f0939b6469dedc2b9ab90
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1666%2Fphilip-peterson%2Fpeterson%2Femail-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1666/philip-peterson/peterson/email-v1
Pull-Request: https://github.com/git/git/pull/1666
-- 
gitgitgadget