$treeview $search $mathjax $extrastylesheet
librsync
2.3.1
$projectbrief
|
$projectbrief
|
$searchbox |
00001 # Callback API {#api_pull} 00002 00003 As an alternative to \ref api_streaming, librsync provides a "pull-mode" 00004 callback interface where it will repeatedly call application-provided 00005 callbacks to get more input data and to accept output data. 00006 00007 Pull jobs are also created using rs_sig_begin(), rs_loadsig_begin,() 00008 rs_delta_begin(), rs_patch_begin(). 00009 00010 However, rather than calling rs_job_iter(), the application should then call 00011 rs_job_drive(), passing an input and an output callback. rs_job_drive() takes 00012 an opaque pointer for both the input and output callback: this could be a 00013 `FILE*` or some similar object telling them what to read and write. 00014 00015 ## Non-blocking IO 00016 00017 The librsync interface allows non-blocking streaming processing of data. 00018 This means that the library will accept input and produce output when it 00019 suits the application. If nonblocking file IO is used and the IO 00020 callbacks support it, then librsync will never block waiting for IO. 00021 00022 Normally callbacks will read/write the whole buffer when they're called, 00023 but in some cases they might not be able to process all of it, or 00024 perhaps not process any at all. This might happen if the callbacks are 00025 connected to a nonblocking socket. Either of two things can happen in 00026 this case. If the callback returns ::RS_BLOCKED, then rs_job_iter() will 00027 also return ::RS_BLOCKED shortly. 00028 00029 When an IO callback blocks, it is the responsibility of the application 00030 to work out when it will be able to make progress and therefore when it 00031 is worth calling rs_job_iter() again. Typically this involves a mechanism 00032 like `poll` or `select` to wait for the file descriptor to be ready. 00033 00034 ## Blocking IO 00035 00036 The IO callbacks are allowed to block. 00037 This will of course mean that the application's call to 00038 rs_job_drive() will also block. 00039 00040 ## Partial completion 00041 00042 IO callbacks are also allowed to process or provide only part of the requested 00043 data, as will commonly happen with socket IO. 00044 00045 The library might not get as much input as it wanted when it is first 00046 called. If it gets a partial read, it needs to hold onto that 00047 valuable and irreplaceable data. 00048 00049 It cannot keep it on the stack, because it will be lost if the read 00050 blocks. It needs to be kept in the job structure, or in somewhere 00051 referenced from there. 00052 00053 The state function probably cannot proceed until it has all the needed 00054 input. So possibly this can be expressed at a high level of the job 00055 structure. Or perhaps it should just be done by each particular state 00056 function. 00057 00058 When the library has output to write out, the callback might not be 00059 able to accept all of it at the time it is called. Deferred outgoing 00060 data needs to be stored in a buffer referenced from the job structure. 00061 00062 I think it's always OK to try to flush this when entering rs_job_iter. 00063 I think it's OK to not do anything else until all the outgoing data 00064 has been flushed. 00065 00066 In many cases we would like to pass a pointer into the input (or 00067 pread) buffer straight to the output callback. In other cases, we 00068 need a different buffer to build up literal outgoing data. 00069 00070 librsync deals with short, bounded-size headers and checksums, and 00071 with arbitrarily-large streaming data. Although the commands are of 00072 bounded size, they are not of fixed size, because there are different 00073 encodings to suit different situations. 00074 00075 The situation is very similar to fetching variable-length headers from 00076 a socket. We cannot read the whole command in a single input, because 00077 we don't know how long it is. As a general principle I think we 00078 should *not* read in too much data and buffer it, because this 00079 complicates things. Therefore we need to read the type byte first, 00080 and then possibly read some parameters.