librsync  2.3.2
stream.h
Go to the documentation of this file.
1 /*= -*- c-basic-offset: 4; indent-tabs-mode: nil; -*-
2  *
3  * librsync -- library for network deltas
4  *
5  * Copyright (C) 2000, 2001 by Martin Pool <mbp@sourcefrog.net>
6  *
7  * This program is free software; you can redistribute it and/or
8  * modify it under the terms of the GNU Lesser General Public License
9  * as published by the Free Software Foundation; either version 2.1 of
10  * the License, or (at your option) any later version.
11  *
12  * This program is distributed in the hope that it will be useful, but
13  * WITHOUT ANY WARRANTY; without even the implied warranty of
14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15  * Lesser General Public License for more details.
16  *
17  * You should have received a copy of the GNU Lesser General Public
18  * License along with this program; if not, write to the Free Software
19  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
20  */
21 
22  /*=
23  | Two wars in a lifetime bear hard on the little places.
24  | In winter when storms come rushing out of the dark,
25  | And the bay boils like a cauldron of sharks,
26  | The old remember the trenches at Paschendale
27  | And sons who died on the Burma Railway.
28  */
29 
30 /** \file stream.h
31  * Manage librsync streams of IO.
32  *
33  * See \sa scoop.c and \sa tube.c for related code for input and output
34  * respectively.
35  *
36  * OK, so I'll admit IO here is a little complex. The most important player
37  * here is the stream, which is an object for managing filter operations. It
38  * has both input and output sides, both of which is just a (pointer,len) pair
39  * into a buffer provided by the client. The code controlling the stream
40  * handles however much data it wants, and the client provides or accepts
41  * however much is convenient.
42  *
43  * At the same time as being friendly to the client, we also try to be very
44  * friendly to the internal code. It wants to be able to ask for arbitrary
45  * amounts of input or output and get it without having to keep track of
46  * partial completion. So there are functions which either complete, or queue
47  * whatever was not sent and return RS_BLOCKED.
48  *
49  * The output buffer is a little more clever than simply a data buffer. Instead
50  * it knows that we can send either literal data, or data copied through from
51  * the input of the stream.
52  *
53  * In buf.c you will find functions that then map buffers onto stdio files.
54  *
55  * So on return from an encoding function, either the input or the output or
56  * possibly both will have no more bytes available.
57  *
58  * librsync never does IO or memory allocation, but relies on the caller. This
59  * is very nice for integration, but means that we have to be fairly flexible
60  * as to when we can `read' or `write' stuff internally.
61  *
62  * librsync basically does two types of IO. It reads network integers of
63  * various lengths which encode command and control information such as
64  * versions and signatures. It also does bulk data transfer.
65  *
66  * IO of network integers is internally buffered, because higher levels of the
67  * code need to see them transmitted atomically: it's no good to read half of a
68  * uint32. So there is a small and fixed length internal buffer which
69  * accumulates these. Unlike previous versions of the library, we don't require
70  * that the caller hold the start until the whole thing has arrived, which
71  * guarantees that we can always make progress.
72  *
73  * On each call into a stream iterator, it should begin by trying to flush
74  * output. This may well use up all the remaining stream space, in which case
75  * nothing else can be done. */
76 
77 size_t rs_buffers_copy(rs_buffers_t *stream, size_t len);
78 
80 int rs_tube_is_idle(rs_job_t const *job);
81 void rs_tube_write(rs_job_t *job, void const *buf, size_t len);
82 void rs_tube_copy(rs_job_t *job, size_t len);
83 
84 void rs_scoop_input(rs_job_t *job, size_t len);
85 void rs_scoop_advance(rs_job_t *job, size_t len);
86 rs_result rs_scoop_readahead(rs_job_t *job, size_t len, void **ptr);
87 rs_result rs_scoop_read(rs_job_t *job, size_t len, void **ptr);
88 rs_result rs_scoop_read_rest(rs_job_t *job, size_t *len, void **ptr);
89 size_t rs_scoop_total_avail(rs_job_t *job);
rs_scoop_input
void rs_scoop_input(rs_job_t *job, size_t len)
Try to accept a from the input buffer to get LEN bytes in the scoop.
Definition: scoop.c:67
rs_result
rs_result
Return codes from nonblocking rsync operations.
Definition: librsync.h:180
rs_tube_catchup
rs_result rs_tube_catchup(rs_job_t *job)
Put whatever will fit from the tube into the output of the stream.
Definition: tube.c:159
rs_tube_copy
void rs_tube_copy(rs_job_t *job, size_t len)
Queue up a request to copy through len bytes from the input to the output of the stream.
Definition: tube.c:200
rs_job
The contents of this structure are private.
Definition: job.h:26
rs_scoop_advance
void rs_scoop_advance(rs_job_t *job, size_t len)
Advance the input cursor forward len bytes.
Definition: scoop.c:117
rs_tube_write
void rs_tube_write(rs_job_t *job, void const *buf, size_t len)
Push some data into the tube for storage.
Definition: tube.c:214
rs_scoop_readahead
rs_result rs_scoop_readahead(rs_job_t *job, size_t len, void **ptr)
Read from scoop without advancing.
Definition: scoop.c:148
rs_scoop_read
rs_result rs_scoop_read(rs_job_t *job, size_t len, void **ptr)
Read LEN bytes if possible, and remove them from the input scoop.
Definition: scoop.c:192
rs_scoop_read_rest
rs_result rs_scoop_read_rest(rs_job_t *job, size_t *len, void **ptr)
Read whatever data remains in the input stream.
Definition: scoop.c:212
rs_buffers_s
Description of input and output buffers.
Definition: librsync.h:322
rs_scoop_total_avail
size_t rs_scoop_total_avail(rs_job_t *job)
Return the total number of bytes available including the scoop and input buffer.
Definition: scoop.c:227