Convert tdb_del to texi. Addresses #52.

git-svn-id: file:///svn/tokudb@1167 c7de825b-a66e-492c-adef-691d508d4ae1

man/tdb_del.3

@@ -1,108 +0,0 @@
-.\" Process this file with
-.\" groff -man -Tascii foo.1
-.\"
-.\" Copyright (c) 2007 Tokutek.  All Rights Reserved.
-.TH DB->del 3 "November 2007" Tokutek "TokuDB Programmer's Manual"
-.SH NAME
-DB->del
-.SH SYNOPSIS
-.LP
-\fB #include <db.h>
-.br
-.sp
-.HP 12
-.BI "int DB->del(DB *" db ,
-.br
-.BI "DB_TXN *" txnid ,
-.br
-.BI "DBT *" key ,
-.br
-.BI "u_int32_t " flags );
-.br
-.SH DESCRIPTION
-.B DB->del
-removes all the key/data pairs that match \fIkey\fR.  If there are
-duplicates, all matching records are removed.
-
-When called on a secondary index (associated via
-\fBDB->associate(3)\fR), all the matching keys in the secondary
-database are used to identify keys/data pairs in the primary database.
-The keys in the primary are all removed, and all the corresponding
-records in all the secondary indices are removed.
-
-.SH PARAMETERS
-.IP \fIdb
-The \fBDB\fR handle for the database\fR.
-.IP \fItxnid
-Either \fBNULL\fR or a \fBTXNID\fR.
-.IP \fIkey
-The key to be deleted.
-.IP \fIflags
-Must be zero or \fBDB_DELETE_ANY\fR.
-Using \fBDB_DELETE_ANY\fR causes \fBDB->del()\fR to return 0 even if
-there are no matching key/data pairs.
-
-
-.SH RETURN VALUE
-.LP
-Returns zero on success.  Success is defined to be that either there
-was at least one matching key/data pair and it was deleted, or there
-were no matching key/data pairs and \fBDB_DELETE_ANY\fR was passed
-(and nothing else went wrong.)
-
-The following non-zero values can be returned:
-.IP \fBDB_NOTFOUND
-If the flags do not include \fBDB_DELETE_ANY\fR and there was no
-matching key/data pair, then return \fBDB_NOTFOUND\fR.
-.IP \fBDB_DEADLOCK
-The system discovered deadlock cycle involving this and other transactions.
-This operation was killed.
-.IP \fBDB_LOCK_NOTGRANTED
-In an environment configured for lock timeouts, the system was unable to grant a lock within the allowed time.
-.IP \fBEINVAL
-You passed invalid parameters to this operation.  In many cases
-\fBEINVAL\fR
-is not a very helpful error code, indicating only that you did something wrong.
-.SH PERFORMANCE DISCUSSION
-
-Performing a deletion without \fBDB_DELETE_ANY\fR is relatively
-expensive.  For example, suppose you have a large database that is
-stored on disk and is much larger than main memory.  Then
-\fBDB->get()\fR using a randomly selected key usually requires at
-least one disk-head movement, limiting you about 100 to 150 get
-operations per second per disk drive.  A delete operation that doesn't
-require the \fBDB_NOTFOUND\fR result to be computed can run much
-faster, however (orders of magnitude faster in some cases.)  For the
-\fBDB->del\fR operation to compute the \fBDB_NOTFOUND\fR result
-requires a get, which slows down the deletions.
-
-However, suppose that the key you are deleting is already in main
-memory (because you recently accessed it).  In that case, there is
-likely to be little or no performance difference between using
-\fBDB_DELETE_ANY\fR or not.
-
-Associated secondary indexes can also slow down deletion operations,
-since TokuDB performs a \fBDB->get\fR to get the primary key/data pair
-so that it can use the callback function to compute all the secondary
-keys that must be deleted.  
-
-One way to achieve fast deletions with secondary indices is to design
-your primary key so that contiguous ranges will be removed from your
-database at the same time.  For example, if you design your primary
-key to be a timestamp, and you expire the oldest data first, then
-deletions can run fast: Use a cursor to find the leftmost item, and
-delete it, move right, delete some more, and so forth.  The cursor
-scan is fast, and the deletes on all the secondary keys will be fast
-too.
-
-.SH CONFORMING TO
-The TokuDB embedded database provides a subset of the functionality of
-the Berkeley DB.  Programs that work with TokuDB probably work with
-with most versions of Berkeley DB with only recompilation or
-relinking.  The database files are incompatible, however, so to
-convert from one library to the other you would need to dump the
-database with one library's tool and load it with the other's.
-.SH AUTHOR
-Tokutek, Inc.
-.SH COPYRIGHT
-Copyright (c) 2007 Tokutek.  All Rights Reserved.

man/texi/Makefile

@@ -1,4 +1,4 @@
-MANPAGES = tdb_create
+MANPAGES = tdb_create tdb_del
 MANPAGES_TEXI = $(patsubst %,%.texi,$(MANPAGES))
 MANPAGES_POD = $(patsubst %,%.pod,$(MANPAGES))
 MANPAGES_3   = $(patsubst %,%.3,$(MANPAGES))

man/texi/everyman.texi

@@ -11,5 +11,9 @@ database with one library's tool and load it with the other's.
 @c man begin COPYRIGHT
 Copyright @copyright{} 2007 Tokutek, Inc.  All rights reserved.
 @c man end
+
+@c man begin AUTHOR
+Tokutek, Inc.
+@c man end
 @end ifnottex
 

man/texi/tdb_create.texi

@@ -60,5 +60,5 @@ TokuDB allows at most a few thousand databases per file.
 @c man end
 
 @include everyman.texi
-@bye
+
 

man/texi/tdb_del.texi

@@ -0,0 +1,97 @@
+@section @code{DB->del}
+@setfilename tokudb
+@settitle DB->del
+
+@c man title db_create tokudb
+@unnumberedsubsec Synopsis
+@c man begin SYNOPSIS
+@code{#include <db.h>}
+
+@code{int DB->del(DB *}@var{db}@code{, DB_TXN *}@var{txnid}@code{, DBT*}@var{key}@code{, u_int32_t }@var{flags}@code{);}
+@c man end
+@unnumberedsubsec Description
+@c man begin DESCRIPTION
+@code{DB->del}
+removes all the key/data pairs that match @var{key}.  If there are
+duplicates, all matching records are removed.
+
+When called on a secondary index (associated via
+@code{DB->associate(3)}), all the matching keys in the secondary
+database are used to identify keys/data pairs in the primary database.
+The keys in the primary are all removed, and all the corresponding
+records in all the secondary indices are removed.
+
+@c man end
+@unnumberedsubsec Parameters
+@c man begin PARAMETERS
+@table @var
+@item db
+The @code{DB} handle for the database.
+@item txnid
+Either @code{NULL} or a @code{TXNID}.
+@item key
+The key to be deleted.
+@item flags
+Must be zero or @code{DB_DELETE_ANY}.
+Using @code{DB_DELETE_ANY} causes @code{DB->del()} to return 0 even if
+there are no matching key/data pairs.
+
+@end table
+
+@c man end
+@unnumberedsubsec Return Value
+@c man begin RETURNVALUE
+Returns zero on success.  Success is defined to be that either there
+was at least one matching key/data pair and it was deleted, or there were zero or more
+matching key/data pairs, and they were all deleted, and @code{BDB_DELETE_ANY} was passed.
+
+The following non-zero values can be returned:
+@table @code
+@item DB_NOTFOUND
+If the flags do not include @code{BDB_DELETE_ANY} and there was no
+matching key/data pair, then @code{DB->del} returns @code{BDB_NOTFOUND}.
+@item DB_DEADLOCK
+The system discovered deadlock cycle involving this and other transactions.
+This operation was killed.
+@item DB_LOCK_NOTGRANTED
+In an environment configured for lock timeouts, the system was unable to grant a lock within the allowed time.
+@item EINVAL
+You passed invalid parameters to this operation.
+@end table
+@c man end
+
+@unnumberedsubsec Notes
+@c man begin NOTES
+
+Performing a deletion without @code{DB_DELETE_ANY} is relatively
+expensive.  For example, suppose you have a large database that is
+stored on disk and is much larger than main memory.  Then
+@code{DB->get()} using a randomly selected key usually requires at
+least one disk-head movement, limiting you about 100 to 150 get
+operations per second per disk drive.  A delete operation that doesn't
+require the @code{DB_NOTFOUND} result to be computed can run much
+faster, however (orders of magnitude faster in some cases.)  For the
+@code{DB->del} operation to compute the @code{DB_NOTFOUND} result
+requires a get, which slows down the deletions.
+
+However, suppose that the key you are deleting is already in main
+memory (because you recently accessed it).  In that case, there is
+likely to be little or no performance difference between using
+@code{DB_DELETE_ANY} or not.
+
+Associated secondary indexes can also slow down deletion operations,
+since TokuDB performs a @code{DB->get} to get the primary key/data pair
+so that it can use the callback function to compute all the secondary
+keys that must be deleted.  
+
+One way to achieve fast deletions with secondary indices is to design
+your primary key so that contiguous ranges will be removed from your
+database at the same time.  For example, if you design your primary
+key to be a timestamp, and you expire the oldest data first, then
+deletions can run fast: Use a cursor to find the leftmost item, and
+delete it, move right, delete some more, and so forth.  The cursor
+scan is fast, and the deletes on all the secondary keys will be fast
+too.
+@c man end
+
+@include everyman.texi

man/texi/tokudb.texi

@@ -35,6 +35,8 @@ Copyright @copyright{} 2007, Tokutek, Inc.
 
 @include tdb_create.texi
 
+@include tdb_del.texi
+
 @node Index
 @unnumbered Index