Below is the list of changes that have just been committed into a local
5.1 repository of rafal. When rafal does a push these changes will
be propagated to the main repository and, within 24 hours after the
push, to the public repository.
For information on how to access the public repository
see http://dev.mysql.com/doc/mysql/en/installing-source-tree.html
ChangeSet@stripped, 2007-04-20 08:15:28+02:00, rafal@quant.(none) +1 -0
WL#3327: Updates to the driver API documentation.
sql/backup/backup_engine.h@stripped, 2007-04-20 08:15:26+02:00, rafal@quant.(none) +178 -148
Documentation updates.
# This is a BitKeeper patch. What follows are the unified diffs for the
# set of deltas contained in the patch. The rest of the patch, the part
# that BitKeeper cares about, is below these diffs.
# User: rafal
# Host: quant.(none)
# Root: /ext/mysql/bk/backup/prototype-push
--- 1.5/sql/backup/backup_engine.h 2007-04-20 08:15:34 +02:00
+++ 1.6/sql/backup/backup_engine.h 2007-04-20 08:15:34 +02:00
@@ -60,8 +60,8 @@
The <code>flags</code> parameter gives additional information about
the backup process to be performed by the driver. Currently, we only set
- <code>Driver::FULL</code> flag if the driver is supposed to backup all the tables
- stored in a given storage engine.
+ <code>Driver::FULL</code> flag if the driver is supposed to backup all the
+ tables stored in a given storage engine.
@param flags (in) additional info about backup operation.
@param tables (in) list of tables to be backed-up.
@@ -81,8 +81,8 @@
The <code>flags</code> parameter gives additional information about
the restore process to be performed by the driver. Currently, we only set
- <code>Driver::FULL</code> flag if the driver is supposed to replace all the tables
- stored in a given storage engine with the restored ones.
+ <code>Driver::FULL</code> flag if the driver is supposed to replace all the
+ tables stored in a given storage engine with the restored ones.
@param version (in) version of the backup image.
@param flags (in) additional info about restore operation.
@@ -128,8 +128,8 @@
being backed-up. This is done by setting <code>table_no</code> member of the
buffer structure to the number of the table to which this data belongs. Tables
are numbered from 1 acoording to their position in the list passed when driver
- is created (<code>m_list</code> member of <code>Driver</code> class). If some
- of the data doesn't correspond to any particular table, then
+ is created (<code>m_tables</code> member of <code>Driver</code> class). If
+ some of the data doesn't correspond to any particular table, then
<code>table_no</code> should be set to 0.
This way, driver can create several "streams" of data blocks. For each table
@@ -197,8 +197,14 @@
A driver is created to backup or restore given list of tables. This list
is passed as an argument when constructing a driver. A reference to
- the list is stored in <code>m_list</code> member for future use (the memory
+ the list is stored in <code>m_tables</code> member for future use (the memory
to store the list is allocated/deallocated by the kernel).
+
+ Driver methods return value of type result_t to inform backup kernel about the
+ result of each operation. If ERROR is returned, it means that the driver is
+ not able to proceed. The kernel will shutdown the driver by calling
+ <code>free()</code> method. No other methods will be called after signalling
+ error by a driver.
*/
class Driver
@@ -289,35 +295,39 @@
<code>begin()</code> call from kernel. Note that any resources should be
allocated inside <code>begin()</code> method, not upon driver
creation.
- -# <b>Initial transfer</b>, when initial data is sent before driver can create a
- <em>validity point</em>. "At end" backup drivers will send majority of their data in this phase.
- -# <b>Waiting for prelock</b>, when driver waits for other drivers to finish sending
- their initial transfer phase. This phase is endend by a call to <code>prelock()</code> method.
- -# <b>Preparing for lock</b>, when driver does neccessary preparatons (if any) to be able
- to instantly crate a validity point upon request from kernel.
- -# <b>Waiting for lock</b>, when driver waits for other drivers to finish their preparations. Phase
- is finished by a call to <code>lock()</code> method.
- -# <b>Synchronization</b>, when the validity point is created inside <code>lock()</code> method.
- For synchronization reasons, data in all tables being backed-up should be frozen during that
- phase. Phase is ended by a call to <code>unlock()</code> method.
- -# <b>Final transfer</b>, when final backup image data (if any) is sent to the kernel.
- "At begin" will send all their data in this phase. This phase is ended by a call to
- <code>end()</code> method.
-
- In each phase, except for the synchronization phase (6), kernel is polling driver using
- <code>get_data()</code> method. Thus a driver has a chance to send data in each phase of the backup
- process. For example, when waiting in phase 3 or 5, driver can send log recording changes which
- happen during that time.
-
- A driver informs the kernel about finishing the initial transfer phase (2) or the lock preparation
- phase (4) by the value returned from the <code>get_data()</code> method (see description of the
- method).
-
- Not all drivers will need all the phases to perform backup but they should still follow the protocol
- and give correct replies from get_data() method.
+ -# <b>Initial transfer</b>, when initial data is sent before driver can create
+ a <em>validity point</em>. "At end" backup drivers will send majority of
+ their data in this phase.
+ -# <b>Waiting for prelock</b>, when driver waits for other drivers to finish
+ sending their initial transfer phase. This phase is endend by a call to
+ <code>prelock()</code> method.
+ -# <b>Preparing for lock</b>, when driver does neccessary preparatons (if any)
+ to be able to instantly crate a validity point upon request from kernel.
+ -# <b>Waiting for lock</b>, when driver waits for other drivers to finish their
+ preparations. Phase is finished by a call to <code>lock()</code> method.
+ -# <b>Synchronization</b>, when the validity point is created inside
+ <code>lock()</code> method. For synchronization reasons, data in all tables
+ being backed-up should be frozen during that phase. Phase is ended by a call
+ to <code>unlock()</code> method.
+ -# <b>Final transfer</b>, when final backup image data (if any) is sent to the
+ kernel. "At begin" will send all their data in this phase. This phase is
+ ended by a call to <code>end()</code> method.
+
+ In each phase, except for the synchronization phase (6), kernel is polling
+ driver using <code>get_data()</code> method. Thus a driver has a chance to send
+ data in each phase of the backup process. For example, when waiting in phase 3
+ or 5, driver can send log recording changes which happen during that time.
+
+ A driver informs the kernel about finishing the initial transfer phase (2) or
+ the lock preparation phase (4) by the value returned from the
+ <code>get_data()</code> method (see description of the method).
+
+ Not all drivers will need all the phases to perform backup but they should
+ still follow the protocol and give correct replies from <code>get_data()</code>
+ method.
- @note The list of tables being backed-up is accesible via <code>m_tables</code> member
- inherited from <code>backup::Driver</code> class
+ @note The list of tables being backed-up is accesible via <code>m_tables</code>
+ member inherited from <code>backup::Driver</code> class
@see Methods <code>begin()</code>, <code>end()</code>, <code>get_data()</code>,
<code>prelock()</code>, <code>lock()</code> and <code>unlock()</code> and
@@ -335,60 +345,66 @@
/**
@fn result_t get_data(Buffer &buf)
- @brief Accept a request for filling a buffer with next chunk of backup data or check
- status of a previously accepted request.
+ @brief Accept a request for filling a buffer with next chunk of backup data
+ or check status of a previously accepted request.
Backup driver can implement its own policy of handling these requests. It can
- return immediately from the call and use a separate thread to fill the buffer or the calling
- thread can be used to do the job. It is also possible that a driver accepts new requests while
- processing old ones, implementing internal queue of requests.
-
- The kernel learns about what happened to the request from the value returned by the method
- (see below). The returned value is also used to inform the kernel that the driver
- has finished the initial transfer phase (2) or the prepare to lock phase (4) (see description
- of the class).
+ return immediately from the call and use a separate thread to fill the buffer
+ or the calling thread can be used to do the job. It is also possible that
+ a driver accepts new requests while processing old ones, implementing
+ internal queue of requests.
+
+ The kernel learns about what happened to the request from the value returned
+ by the method (see below). The returned value is also used to inform the
+ kernel that the driver has finished the initial transfer phase (2) or the
+ prepare to lock phase (4) (see description of the class).
When a request is completed, members of <code>buf</code> should be filled
- as described in the documentation of Buffer class.
- It is possible to complete a request without putting any data in the buffer. In that case
- <code>buf.size</code> should be set to zero. The return value (OK or READY) and the
- <code>buf.stream_no</code> and <code>buf.last</code> members are interpreted as usual. However, no
- data is written to backup archive and such empty buffers are not sent back to restore driver.
-
-
- @param buf (in/out) buffer to be filled with backup data. Its members are initialized by
- backup kernel: <code>buf.data</code> points to a memory area where the
- data should be placed and <code>buf.size</code> is the size of the area. Upon
- completion of the request (<code>OK</code> or <code>READY</code> returned), members
- of <code>buf</code> should be filled as described in the documentation of Buffer
- class.
-
- @retval OK The request is completed - new data is in the buffer and <code>size</code>,
- <code>stream_no</code> and <code>last</code> members of the buffer structure
- are set accordingly.
-
- @retval READY Same as OK and additionaly informs that the initial transfer phase (2) or the
- prepare to lock phase (4) are finished for that driver.
-
- @retval DONE Same as OK but also indicates that the backup process is completed. This result
- can be returned only in the final transfer phase (7).
-
- @retval PROCESSING The request was accepted but is not completed yet. Further calls to get_data()
- are needed to complete it (until it returns OK or READY). Kernel will not reuse the
- bufer before it knows that it is completely filled with data.
+ as described in the documentation of Buffer class. It is possible to complete
+ a request without putting any data in the buffer. In that case
+ <code>buf.size</code> should be set to zero. The return value (OK or READY)
+ and the <code>buf.table_no</code> and <code>buf.last</code> members are
+ interpreted as usual. However, no data is written to backup archive and such
+ empty buffers are not sent back to restore driver.
+
+
+ @param buf (in/out) buffer to be filled with backup data. Its members are
+ initialized by backup kernel: <code>buf.data</code> points to
+ a memory area where the data should be placed and
+ <code>buf.size</code> is the size of the area. Upon completion
+ of the request (<code>OK</code> or <code>READY</code>
+ returned), members of <code>buf</code> should be filled as
+ described in the documentation of Buffer class.
+
+ @retval OK The request is completed - new data is in the buffer and
+ <code>size</code>, <code>table_no</code> and <code>last</code>
+ members of the buffer structure are set accordingly.
+
+ @retval READY Same as OK and additionaly informs that the initial transfer
+ phase (2) or the prepare to lock phase (4) are finished for that
+ driver.
+
+ @retval DONE Same as OK but also indicates that the backup process is
+ completed. This result can be returned only in the final transfer
+ phase (7).
+
+ @retval PROCESSING The request was accepted but is not completed yet. Further
+ calls to get_data() are needed to complete it (until it returns
+ OK or READY). Kernel will not reuse the bufer before it knows
+ that it is completely filled with data.
+
+ @retval BUSY The request can not be accepted now. Kernel can try to place a
+ request later. The buffer is not blocked and can be used for
+ other transfers.
- @retval BUSY The request can not be accepted now. Kernel can try to place a request later. The
- buffer is not blocked and can be used for other transfers.
-
- @retval ERROR An error has happened while processing the request. It is canceled and the buffer
- is released.
+ @retval ERROR An error has happened while processing the request.
@note
If backup kernel calls <code>get_data()</code> when there is no more data
to be sent, the driver should:
- -# set <code>buf.size</code> and <code>buf.stream_no</code> to 0,
+ -# set <code>buf.size</code> and <code>buf.table_no</code> to 0,
-# set <code>buf.last</code> to TRUE,
- -# return <code>OK</code>.
+ -# return <code>DONE</code>.
@see <code>Buffer</code> class.
*/
@@ -401,22 +417,23 @@
@brief Prepare for synchronization of backup image.
- This method is called by backup kernel when all engines participating in creation of
- the backup have finished their initial data transfer. After this call the
- driver should prepare for the following <code>lock()</code> call from the kernel.
-
- It can do the preparations inside the <code>prelock()</code> method if it doesn't
- require too long time. In that case it should return <code>READY</code>.
- If the preparations require longer time (waiting for ongoing operations to finish)
- or sending additional data to the kernel then <code>prelock()</code> should return
- <code>OK</code>. Later on, the kernel will call <code>get_data()</code>
- and driver can signal that it has finished the preparations by returning
- <code>READY</code> result.
+ This method is called by backup kernel when all engines participating in
+ creation of the backup have finished their initial data transfer. After this
+ call the driver should prepare for the following <code>lock()</code> call
+ from the kernel.
+
+ It can do the preparations inside the <code>prelock()</code> method if it
+ doesn't require too long time. In that case it should return
+ <code>READY</code>. If the preparations require longer time (waiting for
+ ongoing operations to finish) or sending additional data to the kernel then
+ <code>prelock()</code> should return <code>OK</code>. Later on, the kernel
+ will call <code>get_data()</code> and driver can signal that it has finished
+ the preparations by returning <code>READY</code> result.
- @retval READY The driver is ready for synchronization, i.e. it can accept the following
- <code>lock()</code> call.
+ @retval READY The driver is ready for synchronization, i.e. it can accept the
+ following <code>lock()</code> call.
- @retval OK The driver is preparing for synchronization. Kernel should call
+ @retval OK The driver is preparing for synchronization. Kernel should call
<code>get_data()</code> and wait until driver is ready.
@retval ERROR The driver can not prepare for synchronization.
@@ -428,26 +445,28 @@
/**
@brief Create vaidity point and freeze all backed-up data.
- After sending <code>prelock()</code> requests to all backup drivers and receiving
- <code>READY</code> confirmations, backup kernell calls <code>lock()</code> method
- of each driver. The driver is supposed to do two things in response:
+ After sending <code>prelock()</code> requests to all backup drivers and
+ receiving <code>READY</code> confirmations, backup kernell calls
+ <code>lock()</code> method of each driver. The driver is supposed to do two
+ things in response:
-# Create a validity point of its backup image. The whole backup image should
describe data at this exact point in time.
- -# Freeze its state until the following <code>unlock()</code> call. This means that
- from now on the data stored in the backed-up tables should not change in any way,
- so that the validity point remains valid during the time other engines create their own
- validity points.
-
- When all drivers have locked, backup kernel will call <code>unlock()</code> on all
- of them. After this call the driver should unfreeze. Kernel will continue polling
- backup data using <code>get_data()</code> method until driver signals that there
- is no more data to be sent.
-
- @note <b>Important!</b>. A call to <code>lock()</code> should return as quickly
- as possible. Ideally, only fast memory access and/or (non-blocking) mutex
- manipulations should happen but no disk operations. The backup kernel
- expects that this call will return in at most few seconds.
+ -# Freeze its state until the following <code>unlock()</code> call. This
+ means that from now on the data stored in the backed-up tables should not
+ change in any way, so that the validity point remains valid during the
+ time other engines create their own validity points.
+
+ When all drivers have locked, backup kernel will call <code>unlock()</code>
+ on all of them. After this call the driver should unfreeze. Kernel will
+ continue polling backup data using <code>get_data()</code> method until
+ driver signals that there is no more data to be sent.
+
+ @note <b>Important!</b>. A call to <code>lock()</code> should return as
+ quickly as possible since it blocks other drivers. Ideally, only fast memory
+ access and/or (non-blocking) mutex manipulations should happen but no disk
+ operations. The backup kernel expects that this call will return in at most
+ few seconds.
@returns Error code or <code>backup::OK</code> upon success.
*/
@@ -457,11 +476,16 @@
/**
@brief Unlock data after the <code>lock()</code> call.
- After call to <code>unlock()</code> driver enters the final data transfer phase. Any
- remaining data should be sent in the following <code>get_data()</code> calls and all
- data streams should be closed. The process is ended by returning
- <code>backup::DONE</code> from the last <code>get_data()</code> call.
- */
+ After call to <code>unlock()</code> driver enters the final data transfer
+ phase. Any remaining data should be sent in the following
+ <code>get_data()</code> calls and all data streams should be closed. The
+ process is ended by returning <code>backup::DONE</code> from the last
+ <code>get_data()</code> call.
+
+ @note <b>Important!</b>. Similar as with <code>lock()</code>, a call to
+ <code>unlock()</code> should return as quickly as possible to not block other
+ drivers.
+ */
virtual result_t unlock() =0;
@@ -480,17 +504,18 @@
/**
Estimate how much data will be sent in the initial phase of backup.
- This information is used by backup kernel to initialize backup drivers of different
- types at correct times. Roughly, drivers with biggest <code>init_size()</code>
- will be initialized and polled first. Drivers whose <code>init_size()</code> is zero,
- will be initialized and polled last in the process.
+ This information is used by backup kernel to initialize backup drivers of
+ different types at correct times. Roughly, drivers with biggest
+ <code>init_size()</code> will be initialized and polled first. Drivers whose
+ <code>init_size()</code> is zero, will be initialized and polled last in the
+ process.
Thus "at begin" drivers which send all backup data in the final phase
- of backup should return 0 here. Drivers of "at end" type should return estimate for
- the size of data to be sent before they are ready for validity point creation.
- If estimating this size is impossible or very expensive, the driver can return
- <code>UNKNOWN_SIZE</code>. In that case the driver will be initialized and polled
- before any other drivers.
+ of backup should return 0 here. Drivers of "at end" type should return
+ estimate for the size of data to be sent before they are ready for validity
+ point creation. If estimating this size is impossible or very expensive, the
+ driver can return UNKNOWN_SIZE. In that case the driver will be initialized
+ and polled before any other drivers.
*/
virtual size_t init_size() =0;
@@ -510,8 +535,8 @@
It is assumed that all tables are blocked during restore process.
- @note The list of tables being restored is accesible via <code>m_tables</code> member
- inherited from <code>backup::Driver</code> class
+ @note The list of tables being restored is accesible via <code>m_tables</code>
+ member inherited from <code>backup::Driver</code> class
@see <code>backup::Driver</code> class.
*/
@@ -529,42 +554,47 @@
@brief Request processing of next block of backup image data or check
status of a previously accepted request.
- Upon restore, backup kernel calls this method periodically sending consecutive
- blocks of data from the backup image. The <code>stream_no</code> field in the
- buffer is set to indicate from which stream the data comes. Also,
- <code>buf.last</code> is <code>TRUE</code> if this is the last block in the stream.
- For each stream the blocks are guaranteed to be sent in the same order in which they
- were received when the backup image was created. However, different streams can be
- interleaved in an arbitrary way.
-
- Restore driver can implement its own policy of handling these requests. It is possible
- that it returns immediately from the call and uses a separate thread to process
- data in the buffer and it is also possible that the calling thread is used to do
- the job.
+ Upon restore, backup kernel calls this method periodically sending
+ consecutive blocks of data from the backup image. The <code>table_no</code>
+ field in the buffer is set to indicate from which stream the data comes.
+ Also, <code>buf.last</code> is TRUE if this is the last block
+ in the stream.
+
+ Blocks are sent to restore driver in the same order in which they were
+ created by a backup driver. This is true also when only selected blocks are
+ sent.
+
+ Restore driver can implement its own policy of handling data processing
+ requests. It is possible that it returns immediately from the call and uses
+ a separate thread to process data in the buffer and it is also possible that
+ the calling thread is used to do the job.
- Returning <code>OK</code> means that the data has been successfuly processed
+ Returning OK means that the data has been successfuly processed
and the buffer can be re-used for further transfers. If method returns
- <code>PROCESSING</code>, it means that the request was accepted but is not completed yet. The buffer should
- not be used for other purposes until a further call to <code>get_data()</code> with
- the same buffer as argument returns <code>OK</code>. A
+ PROCESSING, it means that the request was accepted but is not
+ completed yet. The buffer will not be used for other purposes until a further
+ call to <code>get_data()</code> with the same buffer as argument returns OK.
@param buf (in) buffer filled with backup data. Fields <code>size</code>,
- <code>stream_no</code> and <code>last</code> are set accordingly.
+ <code>table_no</code> and <code>last</code> are set
+ accordingly.
@retval OK The data has been successfuly processed - the buffer can be
used for other transfers.
- @retval DONE Same as OK but also indicates that the restore process is completed.
+ @retval DONE Same as OK but also indicates that the restore process is
+ completed.
@retval PROCESSING The request was accepted but data is not processed yet -
- further calls to <code>send_data()</code> are needed to complete it.
- The buffer is blocked and can't be used for other transfers.
+ further calls to <code>send_data()</code> are needed to
+ complete it. The buffer is blocked and can't be used for other
+ transfers.
@retval BUSY The request can not be processed right now. A call to
<code>send_data()</code> should be repeated later.
- @retval ERROR An error has happened. The request is canceled and the buffer can be
- used for other transfers.
+ @retval ERROR An error has happened. The request is canceled and the buffer
+ can be used for other transfers.
@see <code>Buffer</code> class.
*/
| Thread |
|---|
| • bk commit into 5.1 tree (rafal:1.2524) | rsomla | 20 Apr |
