From: Junio C Hamano <gitster@pobox.com>
Date: Sun, 21 Feb 2010 20:00:07 +0000 (-0800)
Subject: Merge branch 'sp/push-sideband'
X-Git-Tag: v1.7.1-rc0~140
X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/5f8a0de98b727b9bfaea0f3318066109fd6745b8?ds=inline;hp=-c

Merge branch 'sp/push-sideband'

* sp/push-sideband:
receive-pack: Send internal errors over side-band #2
t5401: Use a bare repository for the remote peer
receive-pack: Send hook output over side band #2
receive-pack: Wrap status reports inside side-band-64k
receive-pack: Refactor how capabilities are shown to the client
send-pack: demultiplex a sideband stream with status data
run-command: support custom fd-set in async
run-command: Allow stderr to be a caller supplied pipe
---

5f8a0de98b727b9bfaea0f3318066109fd6745b8
diff --combined Documentation/technical/api-run-command.txt
index 68bf4cad8b,8994859c81..44876fa703
--- a/Documentation/technical/api-run-command.txt
+++ b/Documentation/technical/api-run-command.txt
@@@ -51,7 -51,7 +51,7 @@@ The functions above do the following
    ENOENT; a diagnostic is printed only if .silent_exec_failure is 0.
  
  . Otherwise, the program is run. If it terminates regularly, its exit
 -  code is returned. No diagnistic is printed, even if the exit code is
 +  code is returned. No diagnostic is printed, even if the exit code is
    non-zero.
  
  . If the program terminated due to a signal, then the return value is the
@@@ -64,8 -64,8 +64,8 @@@
  `start_async`::
  
  	Run a function asynchronously. Takes a pointer to a `struct
- 	async` that specifies the details and returns a pipe FD
- 	from which the caller reads. See below for details.
+ 	async` that specifies the details and returns a set of pipe FDs
+ 	for communication with the function. See below for details.
  
  `finish_async`::
  
@@@ -135,7 -135,7 +135,7 @@@ stderr as follows
  
  	.in: The FD must be readable; it becomes child's stdin.
  	.out: The FD must be writable; it becomes child's stdout.
- 	.err > 0 is not supported.
+ 	.err: The FD must be writable; it becomes child's stderr.
  
    The specified FD is closed by start_command(), even if it fails to
    run the sub-process!
@@@ -180,17 -180,47 +180,47 @@@ The caller
     struct async variable;
  2. initializes .proc and .data;
  3. calls start_async();
- 4. processes the data by reading from the fd in .out;
- 5. closes .out;
+ 4. processes communicates with proc through .in and .out;
+ 5. closes .in and .out;
  6. calls finish_async().
  
+ The members .in, .out are used to provide a set of fd's for
+ communication between the caller and the callee as follows:
+ 
+ . Specify 0 to have no file descriptor passed.  The callee will
+   receive -1 in the corresponding argument.
+ 
+ . Specify < 0 to have a pipe allocated; start_async() replaces
+   with the pipe FD in the following way:
+ 
+ 	.in: Returns the writable pipe end into which the caller
+ 	writes; the readable end of the pipe becomes the function's
+ 	in argument.
+ 
+ 	.out: Returns the readable pipe end from which the caller
+ 	reads; the writable end of the pipe becomes the function's
+ 	out argument.
+ 
+   The caller of start_async() must close the returned FDs after it
+   has completed reading from/writing from them.
+ 
+ . Specify a file descriptor > 0 to be used by the function:
+ 
+ 	.in: The FD must be readable; it becomes the function's in.
+ 	.out: The FD must be writable; it becomes the function's out.
+ 
+   The specified FD is closed by start_async(), even if it fails to
+   run the function.
+ 
  The function pointer in .proc has the following signature:
  
- 	int proc(int fd, void *data);
+ 	int proc(int in, int out, void *data);
  
- . fd specifies a writable file descriptor to which the function must
-   write the data that it produces. The function *must* close this
-   descriptor before it returns.
+ . in, out specifies a set of file descriptors to which the function
+   must read/write the data that it needs/produces.  The function
+   *must* close these descriptors before it returns.  A descriptor
+   may be -1 if the caller did not configure a descriptor for that
+   direction.
  
  . data is the value that the caller has specified in the .data member
    of struct async.
@@@ -205,8 -235,8 +235,8 @@@ because this facility is implemented b
  UNIX, but by a thread in the same address space on Windows:
  
  . It cannot change the program's state (global variables, environment,
-   etc.) in a way that the caller notices; in other words, .out is the
-   only communication channel to the caller.
+   etc.) in a way that the caller notices; in other words, .in and .out
+   are the only communication channels to the caller.
  
  . It must not change the program's state that the caller of the
    facility also uses.