oinky 0.1.0

data/ext/include/oinky/nky_table.hpp

@@ -0,0 +1,1996 @@
+//  This source is distributed under the terms of the MIT License.  Refer 
+//  to the 'LICENSE' file for details.
+//  
+//  Copyright (c) Jacob Lacouture, 2012
+
+namespace Oinky
+{
+namespace Internal
+{
+using namespace Oinky::Errors;
+
+//  This is an accessor which can be used for both select and insert.
+//  It defines a column subset and ordering.  This is what gives
+//  a simple sequence of row values its meaning, by binding those values
+//  to specific columns.  As with any accessor, the resulting object
+//  must be destroyed before the host object (the table) is deallocated.
+//
+//  Make a column set from a sequence of column names.  This column set
+//  will then be used in conjunction with the "insert" method to indicate
+//  which columns we're providing values for.  This two-stage insert 
+//  method allows groups of columns to be inserted faster, because
+//  we only have to look up the column names once.  The same columnset
+//  can be used for select.
+template<typename TABLE_CTX>
+class column_selector_template
+{
+protected:
+    typedef TABLE_CTX table_ctx;
+    typedef index_ctx_t<table_ctx> index_ctx;
+    typedef column_selector_template<table_ctx> column_selector_t;
+    
+    friend class table_ctx_t<typename table_ctx::db_t>;
+    friend class index_ctx_t<table_ctx>;
+    friend class table_handle_t<table_ctx>;
+    friend class pending_row<TABLE_CTX>;    
+    friend struct column_selector_accessor<column_selector_t>;
+    template<typename INTERNAL_T, typename HOST_T> friend class cursor_handle_t;
+    
+    table_ctx *table;
+    uint32 tbl_cs_schema;
+    const column_ctx *const *colrefs;
+    uint32 colcount;
+
+    typedef std::vector<const column_ctx *> vector_t;
+    std::tr1::shared_ptr<vector_t> refs;
+    
+    column_selector_template(
+        table_ctx *_table,
+        const column_ctx **_colrefs,
+        uint32 _colcount) :
+    table(_table), 
+        tbl_cs_schema(_table->last_colset_change),
+        colrefs(_colrefs), 
+        colcount(_colcount) 
+    {}
+
+    void check_valid(const table_ctx *_table) const {
+        if ((table != _table) || 
+            (table->last_colset_change != tbl_cs_schema)) 
+        {
+            throw_error(invalid_argument());
+        }
+    }
+
+    //  Most members of this type are hidden because the type is exposed.
+    static column_selector_t select_index(index_ctx *index) {
+        column_selector_t x;
+        x.table = index->table;
+        x.tbl_cs_schema = x.table->last_colset_change;
+        x.colcount = index->defn.col_count;
+        x.colrefs = index->column_refs;
+        return x;
+    }
+
+    static column_selector_t select_all(table_ctx *table) {
+        column_selector_t x;
+        x.table = table;
+        x.tbl_cs_schema = table->last_colset_change;
+        x.colcount = table->cols_by_position.size();
+        x.colrefs = table->cols_by_position.begin();
+        return x;
+    }
+
+    //  This permits duplicate columns, which we certainly want for select,
+    //  but probably not for insert.
+    template<typename COL_NAME_SEQ>
+    column_selector_template(table_ctx *_table, const COL_NAME_SEQ &seq) :
+    table(_table),
+        tbl_cs_schema(_table->last_colset_change)
+    {
+        typedef typename table_ctx::cols_by_name_itr_t cols_by_name_itr_t;
+    
+        uint32 len = seq.size();
+        refs = boost::make_shared<vector_t>(len);
+        
+        typename COL_NAME_SEQ::itr_t s = seq.begin();
+        
+        cols_by_name_itr_t bni;
+        cols_by_name_itr_t bne = table->columns.by_name().end();
+        
+        for (uint32 i = 0; i < len; ++i, ++s) {
+            db_string colname(*s);
+
+            bni = table->columns.by_name().find(colname);
+            if (bni == bne) {
+                throw_error(object_not_found());
+            }
+            column_ctx *ctx = (*bni);
+            (*refs)[i] = ctx;
+        }
+
+        //  Init base.
+        colcount = len;
+        colrefs = &((*refs)[0]);
+    }
+public:
+    column_selector_template() : table(NULL), tbl_cs_schema(0), colrefs(NULL), colcount(0) {}
+
+    uint32 column_count() const { return colcount; }
+    
+    uint32 last_colset_change() const { return tbl_cs_schema; }
+
+    template<typename OSTREAM>
+    void format(OSTREAM &os) const {
+        check_valid(table);
+        
+        //  This prints selected columns in selected order.
+        for (uint32 i = 0; i < colcount; ++i) {
+            const column_ctx *col = colrefs[i];
+            if (!col) {
+                throw_error(invalid_argument());
+            }
+            if (i) {
+                os << ", ";
+            }
+            os << col->colname.as_string();
+        }
+    }
+};
+
+    
+template<typename T>
+struct explode_callbacks 
+{
+    template<typename ROW>
+    static bool call(const column_ctx &cc, T v, ROW *row) {
+        OINKY_ASSERT(cc.ctype != column_types::String);
+        
+        if (cc.ctype == column_types::Variant) {
+            row->set_value(cc, safe_cv_t(v));
+        } else {
+            row->set_value(cc, v);
+        }
+        return true;
+    }
+};
+template<>
+struct explode_callbacks<safe_cv_t> 
+{
+    template<typename ROW>
+    static bool call(const column_ctx &cc, const safe_cv_t &v, ROW *row) {
+        row->set_value(cc, v);
+        return true;
+    }
+};
+
+
+//  All rows are ordered by an internal key.  This is not exposed to the
+//  user, because we reorder it freely.  The key is just an index into the
+//  array of rows.  All rows are exactly the same length, regardless of 
+//  content.  This is because we can put all variable-length data into
+//  the string table.
+//
+//  The key is completely local to the table and its indexes.  It
+//  is never used even as a foreign key to other tables.  Foreign key
+//  relationships are, of course, defined and used by the user, and 
+//  therefore require a user-defined key.
+
+template<typename DB_T>
+class table_ctx_t
+{
+    template<typename X,typename SCHEME> friend class ::Oinky::Serialization::Serializer;
+
+    //  This isn't public to expose to the user, but with the index_ctx,
+    //  pending_row, fixed_t::iterator, etc.
+public:
+    typedef DB_T db_t;
+    typedef typename db_t::allocator_t allocator_t;
+    typedef table_ctx_t<DB_T> table_ctx;
+    typedef index_ctx_t<table_ctx> index_ctx;
+    typedef table_handle_t<table_ctx> table_handle;
+    
+    friend class table_handle_t<table_ctx>;
+
+    struct colmap_traits : default_ctx_map_traits<column_ctx, column_idx_t, allocator_t>
+    {
+        static const mstring_safe &key_from_ctx(const column_ctx *ctx) { 
+            return ctx->colname;
+        }
+        //  Hide the default implementation.
+        static void on_deactivation(const column_ctx *ctx) {}
+    };
+    struct indexmap_traits : default_ctx_map_traits<index_ctx, index_idx_t, allocator_t>
+    {
+        static const mstring_safe &key_from_ctx(const index_ctx *ctx) { 
+            return ctx->indexname;
+        }
+    };
+
+    mstring_safe tablename;
+    ls_marker ls;
+    db_t *db;
+    uint32 last_colset_change;
+    uint32 last_ixset_change;
+
+    //  Every time this table's schema gets altered (new/dropped column/index) 
+    //  we mark the update, invalidating schema caches, such as column_selectors.
+    void mark_colset_change() { 
+        last_colset_change = db->mark_schema_change();
+    }
+    void mark_ixset_change () {
+        last_ixset_change = db->mark_schema_change();
+    }
+
+    bool table_modified_since(sp_marker_t tsp) const { 
+        //  Deleted pending rows.
+        if (dead_pending && (dead_pending->ls.delete_sp > tsp)) {
+            return true;
+        }
+        //  Deleted fixed rows
+        if (fixed_dropped_sp > tsp) {
+            return true;
+        }
+        BOOST_FOREACH(pending_deletes_t::value_type di, pending_deletes)
+        {
+            if (di.second > tsp) { return true; }
+        }
+        cpitr_t pend = live_pending.end();
+        for (
+            cpitr_t pi = live_pending.begin();
+            pi != pend;
+            ++pi
+            ) 
+        {
+            if (pi->ls.insert_sp > tsp) { return true; }
+        }
+
+        if (columns.modified_since(tsp)) {
+            return true;
+        }
+        if (indexes.modified_since(tsp)) {
+            return true;
+        }
+        return false;
+    }
+
+    //  Column definitions
+    typedef context_map_t<colmap_traits> columns_t;
+    typedef typename columns_t::by_name_iterator cols_by_name_itr_t;
+    columns_t columns;
+
+    //  Rows deleted from the fixed set.  
+    //  (Rows deleted from the pending sets are not represented,
+    //   because we just remove them from the live_pending set.)
+    //
+    //  This structure maps the row Id to the SP timestamp which was active
+    //  when it was deleted.  If we rollback to a point before that savepoint
+    //  we will remove the entry from this map.
+    //
+    //  NOTE that we're not using a ls_marker object because the insert is
+    //  implicitly zero.  What we store here is the delete timestamp only.
+    typedef std::tr1::unordered_map<row_idx_t, sp_marker_t> pending_deletes_t; 
+    pending_deletes_t pending_deletes;
+
+    //  This is the serialized table data.  In the common case, where the 
+    //  table structure is unaltered and the bulk of the data was deserialized
+    //  (rather than newly inserted) most of the data is stored here.
+    //
+    //  Note that we iterate over the fixed column set only, since the validity
+    //  of both that set and the fixed values are coincident, and the raw pointer
+    //  iterator is more efficient in the common case.
+    typedef tabledata_fixed<table_ctx> fixed_t;
+    fixed_t fixed;
+    
+    //  Our set of indices.  This structure stores both the serialized indices
+    //  and any new ones.
+    typedef context_map_t<indexmap_traits> indexes_t;
+    indexes_t indexes;
+
+    //  The pending_row object stores column values and index hooks within
+    //  arrays.  Each of those positions maps to the relevant index/column
+    //  descriptor via these maps.  Each context object contains an integer 
+    //  position specifier, providing the reverse mapping.
+    //
+    //  Each of these maps is by reference position (column_itx_t and
+    //  index_idx_t) respectively.  These positions are reused.  In the case
+    //  of indexes, the reference position and storage position are the same,
+    //  and the position is fixed for the lifetime of the index.
+    //  In the case of columns, the positions change whenever a column is added
+    //  or removed, but the storage is not reused.  The usage of the 
+    //  column storage slots is determined separately, using the prow_xxx_xxx
+    //  limit values below.
+    db_vector<column_ctx *> cols_by_position;
+    position_map<index_ctx,true> indexes_by_position;
+    
+    //  While the above column map just provide fast-access to the context 
+    //  objects by pseudo-index, the following are responsible for marking 
+    //  which column storage slots are reserved.
+    //
+    //  Because we do not reuse these positions, we store them as uint32s 
+    //  rather than as column_idx_t values, which could be easily exhausted
+    //  if we create/drop many columns.
+    uint32 prow_byte_limit;
+    //  A bit position is an offset and shift.  
+    uint32 prow_bit_loc;
+    uint8 prow_bit_limit;
+    
+    typedef index_ctx *const *index_positional_itr_t;
+    typedef column_ctx *const *cols_positional_itr_t;
+    
+    //  This is the dynamic row data.  If a row is inserted, it goes here.
+    //  If a row is modified, it gets inserted here, and its index gets
+    //  inserted into the pending_delete_rows table.  We also reinsert it
+    //  into all indexes.
+    typedef pending_row<table_ctx> pending_row_t;
+    typedef typename pending_row_t::row_tree_t row_tree_t;
+    row_tree_t live_pending;
+    pending_row_t *dead_pending;
+    
+    //  Iterators over each container type.
+    typedef typename fixed_t::iterator fixed_itr_t;
+    typedef typename row_tree_t::iterator pitr_t;
+    typedef typename row_tree_t::const_iterator cpitr_t;
+
+    //  Primary ordering for tables (consistent enumeration).
+    //  Secondary ordering for indices (after indexed values, obviously).
+    //  See comment in pending_row::sequence_number.
+    uint64 insert_sequence_limit;
+    
+    //  Some statistics we compute in the first phase of serialization,
+    //  used during the second phase.
+    struct computed_packing_data
+    {
+        uint32 indexset_size;
+        uint32 rowdata_bytes;
+        uint32 total_size;
+        row_offset_accumulator_t row_width;
+    } packing;
+
+    //  Constructor must be safely default-constructible.  Usually we 
+    //  construct, then deserialize into the constructed target.
+    table_ctx_t(db_t *_db = NULL) : 
+    db(_db),
+        last_colset_change(0),
+        last_ixset_change(0),
+        columns(_db ? &_db->allocator : NULL, _db ? &_db->metastrings : NULL),
+        fixed(
+            tabular_t(),
+            this),
+        indexes(_db ? &_db->allocator : NULL, _db ? &_db->metastrings : NULL),
+        cols_by_position(_db ? &_db->allocator : NULL),
+        indexes_by_position(_db ? &_db->allocator : NULL),
+        prow_byte_limit(0),
+        prow_bit_loc(0),
+        prow_bit_limit(0),
+        dead_pending(NULL),
+        insert_sequence_limit(0)
+    {}
+    
+    ~table_ctx_t() {
+        //  We have to invalidate cursors on destruction, in addition to 
+        //  uncreate and drop.  This is to catch the more common database
+        //  teardown case.
+        invalidate_cursors();
+        
+        //  Now delete each pending row.  Theoretically we don't even
+        //  have to clean these up if we're using the pool allocator.
+        //  However, if we're using a global malloc for any reason,
+        //  we'll leak very badly unless we clean these things up, so
+        //  we do.  In general, we don't expect this to be a performance
+        //  problem, since the number of pending rows is generally quite 
+        //  small relative to the size of the instance.
+        //
+        //  This is safe, even though the indices may still reference these
+        //  rows, because we will next destroy the index ctxs, whose
+        //  destructors never touch the pending rows.
+        uncreate_live_rows(0);
+        uncreate_dead_rows(0);
+    }
+    
+    void reinit(db_t *_db)
+    {
+        this->~table_ctx();
+        ::new(this) table_ctx(_db);
+    }
+    
+    bool is_deleted(row_idx_t idx) const {
+        OINKY_ASSERT(idx < fixed.tabular.row_count);
+        //  If we dropped everything, or if 
+        return fixed_dropped() || (pending_deletes.find(idx) != pending_deletes.end());
+    }
+    bool fixed_dropped() const { return fixed_dropped_sp != 0; }
+
+private:    
+    //  If we delete all rows (or explode), we don't bother creating a 
+    //  delete entry for every record.  We just set this value.
+    sp_marker_t fixed_dropped_sp;
+    
+    //  When the table schema is altered (new column added, column deleted, 
+    //  index added, etc, the table gets exploded.  That means we fully 
+    //  deserialize it into pending_row_t structures.
+    //
+    //  We specify the new row width.  This may be larger than the current
+    //  row width.  Preallocating larger rows saves us from having to reallocate
+    //  them later, since we need to store the columns contiguously.
+    //
+    //  The target row width cannot be less than the current row width.  The only
+    //  way to do that would be to explode and delete the column(s) in a 
+    //  single step.
+    void explode(prow_shape_t target_shape)
+    {
+        //  Exploding applies to fixed rows only.
+        if (!fixed_dropped()) {
+            //  How many fixed rows still exist?
+            uint32 newrows = fixed.tabular.row_count - pending_deletes.size();
+
+            if (newrows) {
+                uint32 rowcount = row_count();
+                
+                //  Because we do not create a new tombstone for each deleted
+                //  fixed item, we are effectively adding new rows to the table
+                //  until we batch-delete all the fixed items at the end.
+                //  As we delete, we add to this list.  Then we can proces an
+                //  exception by simply destroying this list.  The space we use 
+                //  for this hook is an extra index allocation (currently 
+                //  unused), but able to be reused in the future.  Once we 
+                //  finish exploding, of course, we can reuse the hook.
+                pending_row_t *undo_head = NULL;
+                uint32 fake_index_idx = indexes_by_position.next_position();
+                
+                try {
+                    //  Make sure we have space for our temporary hook.
+                    if (target_shape.idx_count <= (index_idx_t) fake_index_idx) {
+                        target_shape.idx_count += 1;
+                    }
+                    
+                    //  Advise the allocator that we're about to do a lot of
+                    //  allocation.
+                    db->allocator.prepare(
+                        newrows, 
+                        newrows * pending_row_t::comp_size(target_shape));
+                        
+                    //  Migrate all undeleted fixed rows to pending.
+                    fixed_itr_t fi = fixed.begin();
+                    fixed_itr_t fend = fixed.end();
+                    
+                    for (;fi != fend; ++fi) {
+                        if (fi.is_deleted()) {
+                            continue;
+                        }
+
+                        pending_row_t *row = pending_row_t::make_new(this, target_shape);
+                        OINKY_ASSERT((uint32) row->get_shape().idx_count > fake_index_idx); 
+                        //  Set the lifespan.
+                        row->ls.insert_sp = db->active_sp();
+                        //  The sequence number is the original rowkey.
+                        row->sequence_number = *fi;
+                        //  Copy the column values.
+                        fixed.template each_raw_value<explode_callbacks>(
+                            cols_by_position.begin(), 
+                            cols_by_position.end(), 
+                            *fi, 
+                            row);
+
+                        //  Link each index entry.
+                        this->link_row_indexes(row, true);
+                        
+                        //  And into the table list.
+                        std::pair<pitr_t,bool> ires = live_pending.insert_unique(*row);
+                        OINKY_ASSERT(ires.second);
+                        
+                        //  Link the fake entry
+                        * (pending_row_t **) row->get_hook((index_idx_t) fake_index_idx) = undo_head;
+                        undo_head = row;
+                    }
+                } catch (...) {
+                    //  Unlink and free all the row objects we allocated.
+                    while (undo_head) {
+                        pending_row_t *row = undo_head;
+                        undo_head = * (pending_row_t **) row->get_hook((index_idx_t) fake_index_idx);
+                        
+                        //  There's no reason this try shouldn't succeed, unless
+                        //  the user is failing to synchronize, as we just 
+                        //  created this row.
+                        unlink_row_indexes(row);
+                        live_pending.erase(row_tree_t::s_iterator_to(*row));
+                        row->try_delete();
+                    }
+                    //  re-raise.
+                    throw;
+                } // try
+                
+                //  We haven't dropped the remaining fixed rows yet.
+                OINKY_ASSERT(rowcount + newrows == row_count());
+            } // if (newrows)
+            
+            //  Now drop the entire remaining fixed row set.
+            //  Do this regardless of whether there are any rows to drop, as
+            //  the fixed rows being dropped is used as a test for whether the
+            //  table schema has been altered.
+            fixed_dropped_sp = db->active_sp();
+        }// if (!fixed_dropped())
+    }
+    
+public:
+    //  Compute the minimum row shape required to represent a row
+    //  in this table.
+    //
+    //  We generally presume schema changes are rare.  So new rows
+    //  always use the minimum shape.  Only when growing existing 
+    //  rows do we over-alloc, and that logic is contained entirely 
+    //  within cond_grow_pending_rows.
+    prow_shape_t get_minimum_prow_shape() const
+    {
+        prow_shape_t shape;
+        shape.idx_count = indexes_by_position.limit();
+        shape.column_bytes = prow_byte_limit;
+        return shape;
+    }
+
+    void cond_grow_pending_rows(const prow_shape_t &_ss) 
+    {
+        //  We generally presume schema changes are rare.  So until 
+        //  we see the first schema change, we do not over-alloc.
+        prow_shape_t newshape = prow_shape_t::compute_reserve_shape(get_minimum_prow_shape());
+        
+        newshape.idx_count = MAX(newshape.idx_count, _ss.idx_count);
+        newshape.column_bytes = MAX(newshape.column_bytes, _ss.column_bytes);
+    
+        pitr_t i = live_pending.begin();
+        pitr_t end = live_pending.end();
+        while (i != end) {
+            pending_row_t *pr = &(*i);
+            //  No point growing deleted rows.
+            OINKY_ASSERT(!pr->ls.is_deleted());
+            //  Iterator may have to be reset if the object gets reallocated.
+            pr = pr->cond_grow_self(_ss, newshape);
+            //  The row may have been replaced, invaliding our iterator.
+            i = row_tree_t::s_iterator_to(*pr);
+            ++i;
+        }
+    }
+    
+    void link_row_indexes(pending_row_t *row, bool skip_fixed_rowcheck)
+    {
+        try {
+            index_positional_itr_t end = indexes_by_position.end();
+            for (index_positional_itr_t i = indexes_by_position.begin();i != end; ++i) {
+                if (*i) {
+                    (*i)->link_pending(row, skip_fixed_rowcheck);
+                }
+            }
+        } catch (...) {
+            //  This routine is only intended to be used when we KNOW the 
+            //  index-insertions will succeed.  SP rollback, update-rollback, etc.
+            OINKY_ASSERT(false);
+            throw;
+        }
+    }
+    void unlink_row_indexes(pending_row_t *row)
+    {
+        index_positional_itr_t end = indexes_by_position.end();
+        for (index_positional_itr_t i = indexes_by_position.begin();i != end; ++i) {
+            if (*i) {
+                (*i)->unlink_pending(row);
+            }
+        }
+    }
+
+public:
+    //##############    Select    
+    typedef column_selector_template<table_ctx> column_selector_t;
+    
+    
+    typedef symmetric_iterator<fixed_itr_t> fixed_range_t;
+    typedef symmetric_iterator<pitr_t> pending_range_t;
+
+    struct merge_itr_compare
+    {
+        //  We must always place the fixed before the pending, because we need
+        //  to iterator over dead fixed iterators, but not my more than one place.
+        //  Using a generic filtering iterator over the fixed set doesn't allow
+        //  us to build stable cursors on top of it.
+        template<typename INT>
+        int compare(INT left, INT right) const {
+            if (left < right) return -1;
+            if (left > right) return 1;
+            return 0;
+        }
+        int operator()(const fixed_itr_t &left, const fixed_itr_t &right) const {
+            //  These are both just row indices
+            return compare(*left, *right);
+        }
+        template<typename PITR>
+        int operator()(const PITR &left, const PITR &right) const {
+            return compare(left->sequence_number, right->sequence_number);
+        }
+        template<typename PITR>
+        int operator()(const PITR &left, const fixed_itr_t &right) const {
+            return -(*this)(right,left);
+        }
+        template<typename PITR>
+        int operator()(const fixed_itr_t &left, const PITR &right) const {
+            int k = compare((uint64) *left, right->sequence_number);
+            if (k) {
+                return k;
+            }
+            OINKY_ASSERT(left.is_deleted());
+            return -1;
+        }
+    };
+    
+    struct key_pitr_compare
+    {
+        bool operator()(uint64 left, const pending_row_t &right) const {
+            return merge_itr_compare().compare(left, right.sequence_number) < 0;
+        }
+        bool operator()(const pending_row_t &left, uint64 right) const {
+            return merge_itr_compare().compare(left.sequence_number, right) < 0;
+        }
+    };
+
+    struct pending_to_row {
+        pending_row_t *operator()(const pitr_t &pitr) const {
+            pending_row_t &pr(*pitr);
+            return &pr;
+        }
+        template<typename SAFE_PITR>
+        pending_row_t *operator()(const SAFE_PITR &pitr) const {
+            return pitr.to_row();
+        }
+    };
+    typedef typename iterator_builder<
+        table_ctx, 
+        fixed_itr_t, 
+        fixed_range_t, 
+        pitr_t, 
+        pending_range_t,
+        merge_itr_compare,
+        pending_to_row>::iterator row_iterator;
+
+    //
+    //  TBD:
+    //  A MUCH more efficient way of enumerating would iterate the fixed
+    //  iterator in parallel with the deleted iterator.  Sort of a subtracting-
+    //  merge iterator.  The current implementation does a random-lookup in the
+    //  deleted list for each row.  The reason I haven't fixed it is that the
+    //  behavior is unavoidable for index enumerations.  If it's that big a 
+    //  problem for table enumerations, then a better solution is needed for 
+    //  both.  I'm just hoping it doesn't actually matter at all.
+    //
+
+    row_iterator row_iterator_at(const pitr_t &pi) {
+        //  This is only used to create an iterator aligned with a particular
+        //  pending row.
+        OINKY_ASSERT( pi != live_pending.end() );
+        row_iterator itr(
+            this, 
+            fixed_range_t(fixed.itr_at(pi->sequence_number), fixed.begin(), fixed.end()),
+            pending_range_t(pi, live_pending.begin(), live_pending.end()));
+        //  The fixed itr of the same position should be deleted, or nonexistent.
+        OINKY_ASSERT(itr.pending_active());
+        return itr;
+    }
+
+    row_iterator rows_begin() { 
+        return row_iterator(
+            this, 
+            fixed_range_t(fixed.begin(), fixed.begin(), fixed.end()),
+            pending_range_t(live_pending.begin(), live_pending.begin(), live_pending.end()));
+    }
+    
+    row_iterator rows_end() { 
+        return row_iterator(
+            this, 
+            fixed_range_t(fixed.end(), fixed.begin(), fixed.end()),
+            pending_range_t(live_pending.end(), live_pending.begin(), live_pending.end()));
+    }
+
+    uint32 row_count() const {
+        uint32 fixed_count = fixed_dropped() ? 
+            0 :
+            fixed.tabular.row_count - pending_deletes.size();
+        return fixed_count + live_pending.size(); 
+    }
+        
+private:    
+    void uncreate_idx(index_ctx *idx, sp_marker_t sp)
+    {
+        indexes_by_position.uncreate(idx->index_idx, idx);
+        //  The index has to unlink itself from live rows.
+        idx->uncreate(sp);
+        mark_ixset_change();
+    }
+    void undrop_idx(index_ctx *idx, sp_marker_t sp)
+    {
+        indexes_by_position.undrop(idx->index_idx, idx);
+        //  The index has to relink itself to all live rows.
+        idx->undrop(sp);
+        mark_ixset_change();
+    }
+    //  This means that we are undoing both the create and drop of the
+    //  index.  For us that's a no-op.
+    void uncreate_drop_idx(index_ctx *idx, sp_marker_t sp)
+    {}
+
+    void rollback_prow_data_allocation(column_ctx *col)
+    {
+        //  Roll back our storage limits.
+        if (col->is_bit()) {
+            //  The bit-byte-limit (bit_loc) is on a separate stack from
+            //  the byte-limit (byte_limit).  We have to roll back the 
+            //  bit limit only.
+            if (col->prow_byte_offset <= prow_bit_loc) 
+            {
+                //  Under byte_offset equality, we need a more strict test 
+                //  for moving the bit limit.  If the byte offset is less,
+                //  then we always move th emit limit.
+                if ((col->prow_byte_offset < prow_bit_loc) || (col->prow_bit_offset < prow_bit_limit)) {
+                    prow_bit_limit = col->prow_bit_offset;
+                }
+                
+                prow_bit_loc = col->prow_byte_offset;
+                
+                if (col->prow_bit_offset == 0) {
+                    //  The stacks align for bit-columns where the bit_offset 
+                    //  is zero.  In this case, the bit allocation was done at
+                    //  the end of the byte stack, so we can roll that back also
+                    //  (as always, assuming it hasn't been done already).
+                    if (col->prow_byte_offset < prow_byte_limit) {
+                        prow_byte_limit = col->prow_byte_offset;
+                    } else {
+                        //  Equality here should NEVER occur.
+                        OINKY_ASSERT(col->prow_byte_offset != prow_byte_limit);
+                    }
+                }
+            } 
+        } else {
+            if (col->prow_byte_offset < prow_byte_limit) {
+                prow_byte_limit = col->prow_byte_offset;
+            }
+        }
+    }
+
+    void uncreate_col(column_ctx *col, sp_marker_t sp)
+    {
+        //  Roll back our storage limits.
+        rollback_prow_data_allocation(col);
+        mark_colset_change();
+    }
+    void undrop_col(column_ctx *col, sp_marker_t sp)
+    {
+        mark_colset_change();
+    }
+    //  Roll back both the create and drop, in reverse order.  The undrop
+    //  is nothing for us.  We just have to roll back the allocation.
+    void uncreate_drop_col(column_ctx *col, sp_marker_t sp)
+    {
+        rollback_prow_data_allocation(col);
+    }
+
+    //  This deletes live rows that were created since the target SP
+    void uncreate_live_rows(sp_marker_t tsp)
+    {
+        pitr_t pend = live_pending.end();
+        for (
+            pitr_t pi = live_pending.begin();
+            pi != pend;
+            //NOTHING
+            ) 
+        {
+            pending_row_t *row(&(*pi));
+            OINKY_ASSERT(row->ls.delete_sp == 0);
+            
+            //  If the row is newer than the SP, delete it outright.
+            if (row->ls.insert_sp > tsp) {
+                ++pi;
+                unlink_row_indexes(row);
+
+                //  Remove the core list entry.
+                live_pending.erase(row_tree_t::s_iterator_to(*row));
+                row->try_delete();
+                continue;
+            }
+            //  next.
+            ++pi;
+        }
+    }
+
+    //  This permenently deletes erased or overwritten rows that were 
+    //  orginally created after the target SP.
+    void uncreate_dead_rows(sp_marker_t tsp)
+    {
+        pending_row_t **parent = &dead_pending;
+        while (*parent) {
+            pending_row_t *row = *parent;
+            
+            OINKY_ASSERT(row->ls.delete_sp != 0);
+            
+            //  If the row is newer than the SP, delete it outright.
+            if (row->ls.insert_sp > tsp) {
+                //  Remove this item from the list.
+                *parent = *(pending_row_t **)row;
+                row->try_delete();
+                continue;
+            } else if (row->ls.delete_sp <= tsp) {
+                //  We insert into the dead list at the front, during row delete.  
+                //  During SP rollback, we can stop as soon as we encounter a 
+                //  record which was deleted before the SP target.
+                break;
+            } else {
+                //  We can't early-out in this case.  There may be elements
+                //  beyond this one that need to be deallocated.
+                parent = (pending_row_t **)row;
+            }
+        }
+    }
+    
+    //  This moves rows from the dead list back to the live list.  The
+    //  dead-list is reverse-ordered by deletion SP, so we undelete everything
+    //  up to the limit and then stop.  No need to go to the end.
+    void undelete_dead_rows(sp_marker_t tsp)
+    {
+        while (dead_pending) {
+            pending_row_t *row = dead_pending;
+            
+            OINKY_ASSERT(row->ls.insert_sp <= tsp);
+            
+            //  If the row is newer than the SP, delete it outright.
+            if (row->ls.delete_sp > tsp) {
+                //  Undelete.
+                row->ls.delete_sp = 0;
+
+                //  Remove from the dead-list.
+                //  Extract the next item and then reinit the row hook, which we
+                //  corrupted by sticking it on our list
+                dead_pending = *(pending_row_t **)row;
+                row_tree_hook *hook = row;
+                ::new(hook) row_tree_hook();
+
+                //  Put it on the live list.
+                std::pair<pitr_t,bool> ires = live_pending.insert_unique(*row);
+                OINKY_ASSERT(ires.second);
+                
+                //  Put it back in the indexes.
+                link_row_indexes(row, true);
+                
+                continue;
+            } else {
+                //  Early out because dead-list is sorted on delete_sp.
+                break;
+            }
+        }
+    }
+    
+public:
+    //  We rollback to a target sp.  Anything marked later than this sp gets
+    //  deleted.  rolling back to 0 deletes anything marked >= 1, which is
+    //  everything but the original data.
+    //
+    //  Rolling back to a savepoint never causes allocation.
+    void sp_rollback(sp_marker_t tsp)
+    {
+        //  Nothing within this block should raise.  The catch is just
+        //  to confirm that.
+        try {
+            //  First we un-insert rows, then we modify the indexes, and then
+            //  we un-delete rows.  We do things in this order to 
+            //  avoid generating index uniqueness violations with intermediate
+            //  row state which never existed.  This is a challenge because
+            //  row rollback and index are processed in separate batches, rather
+            //  than in strictly reverse-chronological order.  
+            uncreate_live_rows(tsp);
+            //  And do the same for the dead list.
+            uncreate_dead_rows(tsp);
+            
+            //  Now un-delete the fixed entries.
+            pending_deletes_t::iterator dend = pending_deletes.end();
+            for (
+                pending_deletes_t::iterator di = pending_deletes.begin();
+                di != dend;
+                //NOTHING
+                ) 
+            {
+                if (di->second > tsp) { 
+                    pending_deletes_t::iterator tmp = di;
+                    ++di;
+                    pending_deletes.erase(tmp);
+                } else {
+                    ++di;
+                }
+            }
+            //  Conditionally un-explode the fixed data.
+            if (fixed_dropped_sp > tsp) {
+                fixed_dropped_sp = 0;
+            }
+            
+            //  Now that we have deleted all the pending rows (and unlinked their
+            //  index hooks) we can uncreate/undrop any indexes that have been
+            //  created/dropped since the SP.
+            indexes.sp_rollback(
+                tsp, 
+                boost::bind(&table_ctx::uncreate_idx, this, _1, _2), 
+                boost::bind(&table_ctx::undrop_idx, this, _1, _2),
+                boost::bind(&table_ctx::uncreate_drop_idx, this, _1, _2));
+            
+            //  Now rollback the indexes themselves.  This includes the set that
+            //  has been undropped, but not those that have been uncreated.  It
+            //  also includes those which have been neither undropped nor uncreated.
+            index_positional_itr_t idxend = indexes_by_position.end();
+            for (index_positional_itr_t idxi = indexes_by_position.begin(); idxi != idxend; ++idxi) {
+                if (*idxi) {
+                    (*idxi)->sp_rollback(tsp);
+                }
+            }
+            
+            //  Bring back deleted rows.
+            undelete_dead_rows(tsp);
+
+            //  Now undrop/uncreate columns.
+            //  This can really be done at any point in the rollback process.
+            //  It's orthogonal to row/index rollback, since none of those 
+            //  processes touch the column contexts.
+            //
+            //  Unlike the index rollback, these callbacks do not update
+            //  cols_by_position.  We just rebuild that from scratch after
+            //  teh columns are all restored.
+            columns.sp_rollback(
+                tsp, 
+                boost::bind(&table_ctx::uncreate_col, this, _1, _2), 
+                boost::bind(&table_ctx::undrop_col, this, _1, _2),
+                boost::bind(&table_ctx::uncreate_drop_col, this, _1, _2));
+                
+            //  Now we reassign the colmap from scratch.
+            rebuild_cols_by_position();
+        } catch (...) {
+            //  An exception here is an internal bug.
+            //
+            //  Nothing should throw within this block.  We're not allocating
+            //  memory, and theoretically we're not creating any state which
+            //  didn't exist before.  Furthermore, we do all the deletions
+            //  prior to all the insertions, so we should not violate any
+            //  uniqueness constraints during the intermediate states.
+            OINKY_ASSERT(false);
+            throw;
+        }
+    }
+    
+private:    
+    void rebuild_cols_by_position()
+    {
+        cols_by_name_itr_t cn_i = columns.by_name().begin();
+        cols_by_name_itr_t cn_end = columns.by_name().end();
+        cols_by_position.resize(std::distance(cn_i, cn_end));
+        column_ctx **cbp_i = cols_by_position.begin();
+        for (;cn_i != cn_end; ++cn_i, ++cbp_i) {
+            *cbp_i = *cn_i;
+        }
+    }
+
+    void erase_pending(pending_row_t *row, bool unlink_all) 
+    {
+        //  Should not yet be deleted.
+        OINKY_ASSERT(row->ls.insert_sp > 0);
+        OINKY_ASSERT(row->ls.delete_sp == 0);
+        
+        //  Double-delete is a very dangerous misuse by the caller, likely
+        //  caused by using an invalid iterator.  It's one of the few such
+        //  usage errors we check for even in production builds.
+        if (row->ls.delete_sp != 0) {            
+            throw_error(invalid_argument());
+        }
+    
+        //  Set the delete SP and optionally unlink index entries.
+        row->ls.delete_sp = db->active_sp();
+        OINKY_ASSERT(row->ls.insert_sp <= row->ls.delete_sp);
+        if (unlink_all) {
+            unlink_row_indexes(row);
+            
+            //  Remove from the active-list.
+            live_pending.erase(row_tree_t::s_iterator_to(*row));
+        }
+        
+        //  If we insert/delete in the same savepoint, we can remove aggressively.
+        if (row->ls.insert_sp == row->ls.delete_sp) {
+            row->try_delete();
+            return;
+        }
+    
+        //  Otherwise, we'll keep the row around on the dead-list, so
+        //  we can rollback if we need to.
+        *(pending_row_t **)row = dead_pending;
+        dead_pending = row;
+    }
+    
+    void erase_fixed(row_idx_t offset)
+    {
+        //  Should not yet be deleted.
+        OINKY_ASSERT(pending_deletes.find(offset) == pending_deletes.end());
+        //  Where asserts are not active, but there is still a usage error
+        //  causing a repeated delete, this will not alter the delete timestamp.
+        //  So a sp rollback to before current will not un-delete, which is
+        //  the desired behavior.  Redundant-deletes are consistent no-ops.
+        pending_deletes.insert(std::make_pair(offset, db->active_sp()));
+    }
+    void unerase_fixed(row_idx_t offset)
+    {
+        //  Should be deleted.
+        pending_deletes_t::iterator i = pending_deletes.find(offset);
+        OINKY_ASSERT(i != pending_deletes.end());
+        pending_deletes.erase(i);
+    }
+
+public:
+    //  This invalidates the iterator, and any other iterator to this object,
+    //  obviously.
+    void erase(const row_iterator &pos) 
+    {
+        if (pos.pending_active()) {
+            erase_pending(&(*pos.pending()), true);
+        } else {
+            erase_fixed(*pos.fixed());
+        }
+    }
+
+    //  Replace the row identified by itr with a row defined by the new values.
+    //  All existing iterators to this row are invalidated.  The parameter iterator
+    //  gets reassigned to the new row.  Iterators to any other row are unaffected.
+    template<typename SEQ_T>
+    void update_row(row_iterator &itr, const column_selector_t &cols, const SEQ_T &values) 
+    {
+        if (itr.pending_active()) {
+            pitr_t pitr = itr.pending();
+            pending_row_t *row = update_dynamic_row(&(*pitr), cols, values);
+            itr = row_iterator_at(row_tree_t::s_iterator_to(*row));
+        } else {
+            fixed_itr_t fitr = itr.fixed();
+            itr = update_fixed_row(*fitr, cols, values);
+        }
+    }
+    
+private:
+    template<typename SEQ_T>
+    pending_row_t *update_dynamic_row(pending_row_t *row, const column_selector_t &cols, const SEQ_T &values) 
+    {
+        //  Verify that the selector is still current.
+        cols.check_valid(this);
+    
+        try {
+            //  First unlink the existing row.
+            unlink_row_indexes(row);
+            
+            //  If we can reuse the row, then we will.  Otherwise, we'll 
+            //  simply call insert_row to do the work of creating 
+            //  and initializing a new one.
+            //
+            //  We can only reuse the row if it's large enough, and if the
+            //  sp hasn't advanced.  Also, if there is no existing cursor
+            //  on the row.
+            if ((row->ls.insert_sp == db->active_sp()) &&
+                (row->get_shape().column_bytes >= prow_byte_limit) &&
+                (row->crs_ref_count() == 0)) 
+            {
+                //  This will save the values and insert the row into each
+                //  of the indexes, based on these new values.  If insertion
+                //  fails, it will unwind all index insertions and restore
+                //  the original column values to the row.
+                //
+                //  We will then restore the previous index links in the 
+                //  exception handler below.
+                store_and_index_row_values(row, true, cols, values);
+                
+                //  Return the original row.
+                return row;
+            } else {
+                pitr_t hint = row_tree_t::s_iterator_to(*row);
+                pitr_t old = hint;
+                ++hint;
+                live_pending.erase(old);
+                
+                try {
+                    //  This can fail due to allocation error, uniqueness constraint, etc...
+                    pitr_t pi = insert_row(
+                        cols, 
+                        values, 
+                        hint, 
+                        boost::bind(&table_ctx::fill_row_clone_pending,this,row,_1),
+                        &row->sequence_number
+                        );
+                    
+                    //  Preserve the sequence number, since this is the same logical row.
+                    pending_row_t &nr = *pi;
+                    OINKY_ASSERT(nr.sequence_number == row->sequence_number);
+
+                    //  Erase the old row.  Do NOT unlink the index entries 
+                    //  or the live_pending links again.
+                    //
+                    //  This will preserve the row on the deleted list if the SP 
+                    //  has moved since it was inserted.
+                    erase_pending(row, false);
+                    
+                    //  Return the new row.
+                    return &nr;
+                } catch (...) {
+                    pitr_t p = live_pending.insert_unique(hint, *row);
+                    OINKY_ASSERT(&(*p) == row);
+                    throw;
+                }
+            }
+        } catch (...) {
+            //  Either store_and_index_row_values's index insertion or 
+            //  insert_row's allocation/index insertion raised.
+            //
+            //  The old row data remains valid.  Simply restore the old row hooks.
+            link_row_indexes(row, true);
+            throw;
+        }
+    }
+
+    template<typename SEQ_T>
+    row_iterator update_fixed_row(row_idx_t fixedpos, const column_selector_t &cols, const SEQ_T &values) 
+    {
+        try {
+            //  We erase the existing row before trying to insert, to avoid
+            //  spurious uniqueness violations.
+            
+            //  This allocation can fail.
+            erase_fixed(fixedpos);
+            
+            //  This can fail due to allocation error, uniqueness constraint, etc...
+            uint64 seq = (uint64) fixedpos;
+            pitr_t pi = insert_row(
+                cols, 
+                values, 
+                live_pending.begin(), 
+                boost::bind(&table_ctx::fill_row_clone_fixed, this, fixedpos, _1),
+                &seq
+                );
+            return row_iterator_at(pi);
+        } catch (...) {
+            //  Restore previous state.
+            unerase_fixed(fixedpos);
+            throw;
+        }
+    }
+
+private:
+    template<typename SEQ_T>
+    void store_and_index_row_values(pending_row_t *row, bool save_values, const column_selector_t &cols, const SEQ_T &values) 
+    {
+        uint32 save_bytes = row->get_shape().column_bytes;
+        void *saved_values = NULL;
+        if (save_values) {
+            saved_values = alloca(save_bytes);
+            memcpy(saved_values, row->column_data(), save_bytes);
+        }
+        
+        index_positional_itr_t begin = indexes_by_position.begin();
+        index_positional_itr_t end = indexes_by_position.end();
+        index_positional_itr_t i = begin;
+        
+        try {
+            //  Now we'll iterate through the row values as passed to us and
+            //  check the type/save the value.
+            typename SEQ_T::itr_t rvi = values.begin();
+            const column_ctx *const *ci = cols.colrefs;
+            for (; rvi != values.end(); ++rvi, ++ci) {
+                OINKY_ASSERT(*ci);
+                const column_ctx &col(**ci);
+                //  The given value should be variant.
+                variant_cv_t cv(*rvi);
+                //  Save the value.  This does a type-check/cast too.
+                row->set_value(col, safe_cv_t(col.type(), cv, &db->userstrings));
+            }
+            
+            //  Insert a row for each index.
+            for (i = begin; i != end; ++i) {
+                if (*i) {
+                    (*i)->link_pending(row, false);
+                }
+            }
+        } catch (...) {
+            //  On exception, we must remove the row from each index.
+            for (;i != begin;) {
+                //  The exception was for the current i position.  So we 
+                //  advance to the previous.
+                --i;
+                if (*i) {
+                    (*i)->unlink_pending(row);
+                }
+            }
+            
+            //  Restore original values, if saved.
+            if (saved_values) {
+                memcpy(row->column_data(), saved_values, save_bytes);
+            }
+            
+            //  Pass the exception to caller.
+            throw;
+        }
+    }
+    
+public:
+    void fill_row_defaults(pending_row_t *target) const 
+    {
+        //  Now assign to each column the default value, since the 
+        //  row given to us by the caller is not complete.
+        cols_positional_itr_t ci = cols_by_position.begin();
+        cols_positional_itr_t endcols = cols_by_position.end();
+        for (;ci != endcols;++ci) {
+            target->set_value(**ci, (*ci)->default_value);
+        }
+    }
+
+    void fill_row_clone_pending(const pending_row_t *source, pending_row_t *target) const
+    {
+        //  cp_bytes are the amount currently in use.  Either row may be 
+        //  over-allocated.
+        uint32 cp_bytes = get_minimum_prow_shape().column_bytes;        
+        OINKY_ASSERT(target->get_shape().column_bytes >= cp_bytes);
+        OINKY_ASSERT(source->get_shape().column_bytes >= cp_bytes);
+        
+        memcpy(target->column_data(), source->column_data(), cp_bytes);
+    }
+
+    void fill_row_clone_fixed(row_idx_t fixedpos, pending_row_t *target) const
+    {
+        uint32 cp_bytes = get_minimum_prow_shape().column_bytes;        
+        OINKY_ASSERT(target->get_shape().column_bytes <= cp_bytes);
+
+        //  We basically just explode the fixed row into the target, and then
+        //  modify the exploded row.
+        fixed.template each_raw_value<explode_callbacks>(
+            cols_by_position.begin(), 
+            cols_by_position.end(), 
+            fixedpos, 
+            target);
+    }
+
+    template<typename SEQ_T, typename TEMPLATE>
+    pitr_t insert_row(
+        const column_selector_t &cols, 
+        const SEQ_T &values, 
+        const pitr_t &hint, 
+        TEMPLATE templatefn,
+        const uint64 *sequence_number = NULL) 
+    {
+        //  Verify that the selector is still current.
+        cols.check_valid(this);
+    
+        //  Verify that we have enough values.
+        if (cols.colcount != values.size()) {
+            throw_error(invalid_argument());
+        }
+        
+        //  This will create the pending-row object with sufficient column 
+        //  entries and index hooks.
+        pending_row_t *row = pending_row_t::make_new(this);
+
+        //  Try-catch to deallocate.
+        //  Can't use auto-ptr because delete is private.
+        try {
+            row->ls.insert_sp = db->active_sp();
+
+            //  Store the default values in the row.  (These can come from
+            //  the column-defaults, or from the row we are overwriting).
+            templatefn(row);
+            
+            //  Assign the row the given sequence number, or a new one.
+            if (sequence_number) {
+                row->sequence_number = *sequence_number;
+            } else {
+                row->sequence_number = insert_sequence_limit;
+                ++insert_sequence_limit;
+            }
+            
+            //  This will raise an exception if any of the indexes can't be 
+            //  joined due to a uniqueness constraint.  It is guaranteed to 
+            //  be complete either way.  All indexes will be joined or none.
+            //
+            //  We do this FIRST because it's the only thing that can fail, and 
+            //  so we don't have to worry about undoing anything else if it does.
+            store_and_index_row_values(row, false, cols, values);
+
+            //  Nothing further will fail.
+            
+            //  Ordering is important here.  We don't have to undo this
+            //  in the exception handler if it's the last thing we do.
+            pitr_t ires = live_pending.insert_unique(hint, *row);
+            OINKY_ASSERT(&(*ires) == row);
+            
+            //  Return an iterator to the new row.
+            return ires;
+        } catch (...) {
+            row->try_delete();
+            throw;
+        }
+    }
+
+
+    struct safe_tbl_cursor_host
+    {
+        table_ctx *tbl;
+        safe_tbl_cursor_host(table_ctx *_tbl) : tbl(_tbl) {}
+        safe_tbl_cursor_host() : tbl(NULL) {}
+
+        bool operator==(const safe_tbl_cursor_host &other) const {
+            return tbl == other.tbl;
+        }
+        bool operator!=(const safe_tbl_cursor_host &other) const {
+            return tbl != other.tbl;
+        }
+        
+        allocator_t &allocator() const { return tbl->db->allocator; }
+        
+        table_ctx *table() const { return tbl; }
+    
+        void check_state() const
+        {
+            if (tbl->ls.is_deleted()) {
+                throw_error(object_deleted());
+            }
+        }
+
+        //  Alternatives are lower/upper bound.  Depends on fwd/reverse
+        pending_row_t *seek_pending(bool use_lower_bound, pending_row_t *row) const
+        {
+            OINKY_ASSERT(row->is_inactive());
+            
+            //  The table cursor just searches by sequence number.
+            pitr_t h;
+            if (use_lower_bound) {
+                h = tbl->live_pending.lower_bound(row->sequence_number, key_pitr_compare());
+            } else {
+                h = tbl->live_pending.upper_bound(row->sequence_number, key_pitr_compare());
+            }
+            if (h == tbl->live_pending.end()) {
+                return NULL;
+            }
+            return &(*h);
+        }
+        
+        pending_row_t *seek_prev(pending_row_t *row) const {
+            pitr_t h;
+            if (row == NULL) {
+                h = tbl->live_pending.end();
+            } else {
+                h = row_tree_t::s_iterator_to(*row);
+            }
+            
+            if (h == tbl->live_pending.begin()) {
+                return NULL;
+            } else {
+                --h;
+                return &(*h);
+            }
+        }
+        pending_row_t *seek_next(pending_row_t *row) const {
+            pitr_t h;
+            if (row == NULL) {
+                h = tbl->live_pending.begin();
+            } else {
+                h = row_tree_t::s_iterator_to(*row);
+                ++h;
+            }
+            
+            if (h == tbl->live_pending.end()) {
+                return NULL;
+            } else {
+                return &(*h);
+            }
+        }
+
+        //  Link/Unlink the internal cursor object from the host list.
+        template<typename INTERNAL>
+        void unlink_cursor(INTERNAL *i) {
+            tbl->active_cursors.erase(table_ctx::active_cursors_t::s_iterator_to(*i));
+        }
+        template<typename INTERNAL>
+        void link_cursor(INTERNAL *i) {
+            tbl->active_cursors.push_back(*i);
+        }
+
+        inline void assert_row_valid(pending_row_t *row) const {
+            OINKY_ASSERT(row && (row->table() == tbl));
+        }
+    };
+    
+    class safe_pending_cursor : public safe_pending_cursor_t<pending_row_t, safe_tbl_cursor_host>
+    {
+        typedef safe_pending_cursor_t<pending_row_t, safe_tbl_cursor_host> base_t;
+    public:
+        using base_t::host;
+        using base_t::to_row;
+        
+        safe_pending_cursor() {}
+        
+        safe_pending_cursor(const safe_tbl_cursor_host &_host, pending_row_t *_row, bool _bbegin) :
+        base_t(_host, _row, _bbegin)
+        {}
+        
+        const safe_pending_cursor &i() const { return *this; }
+    };
+
+    typedef typename iterator_builder<
+        table_ctx, 
+        fixed_itr_t, 
+        fixed_range_t, 
+        safe_pending_cursor,
+        safe_pending_cursor,
+        merge_itr_compare,
+        pending_to_row>::iterator safe_itr_t;
+
+    typedef cursor_internal_t<safe_itr_t> cursor_internal;
+    typedef cursor_handle_t<cursor_internal, safe_tbl_cursor_host> cursor_handle;
+
+    //
+    //  We keep track of all the active cursors on this table.  (excluding the 
+    //  indices).  We invalidate them when the index gets dropped or uncreated.
+    //
+    typedef boost::intrusive::list<cursor_internal> active_cursors_t;
+    active_cursors_t active_cursors;
+    
+    void invalidate_cursors()
+    {
+        while (active_cursors.begin() != active_cursors.end()) {
+            typename active_cursors_t::iterator i = active_cursors.begin();
+            i->invalidate();
+            active_cursors.erase(i);
+        }
+    }
+    
+    //  Invoked when the table is dropped from the DB, or when a create is rolled back via SP.
+    void on_deactivation() { 
+        invalidate_cursors();
+        db->mark_schema_change();
+    }
+
+    void make_column(column_ctx *target, const mstring_safe &colname, table_column_def def)
+    {
+        //  Set the column name
+        target->colname = colname;
+        
+        //  Must set the type before calling internalize.
+        target->ctype = def.column_type;
+        //  This can throw if internalization requires an allocation.
+        target->default_value = target->internalize(def.default_value, &db->userstrings);
+        //  This can throw if we can't obtain a reference position.
+        cols_by_position.resize(cols_by_position.size() + 1);
+        //  ** Nothing beyond here should throw.
+
+        //  Determine which bytes in the pending_row will be reserved for 
+        //  these column values.
+        allocate_pending_column_data(target);
+
+        mark_colset_change();
+    }
+
+    void allocate_pending_column_data(column_ctx *col)
+    {
+        //  Assign storage in the prow objects.
+        if (col->is_bit()) {
+            if (prow_bit_limit == 0) {
+                col->prow_byte_offset = prow_bit_loc = prow_byte_limit;
+                col->prow_bit_offset = 0;
+                prow_byte_limit += 1;
+                prow_bit_limit = 1;
+            } else {
+                col->prow_byte_offset = prow_bit_loc;
+                col->prow_bit_offset = prow_bit_limit;
+                prow_bit_limit = (prow_bit_limit + 1) & 7;
+            }
+        } else {
+            col->prow_byte_offset = prow_byte_limit;
+            col->prow_bit_offset = 0;
+            prow_byte_limit += compute_pending_width(col->ctype);
+        }
+    }
+
+    template<typename ITR_T>
+    void make_index(
+        index_ctx *index, 
+        const mstring_safe &name, 
+        index_uniqueness_spec_t uniq, 
+        ITR_T cbegin, 
+        ITR_T cend) 
+    {
+        //  This must be an iterator over public column defs, which reference 
+        //  columns by name.
+        BOOST_STATIC_ASSERT((boost::is_same<
+            typename boost::iterator_value<ITR_T>::type,
+            index_column_def>::value));
+    
+        //  Determine which set of hooks the index will use.  Any slot vacated
+        //  by a dropped index is fair game, but we may have to grow the map,
+        //  which can raise.
+        index_idx_t index_idx = (index_idx_t) indexes_by_position.next_position();
+        
+        //  Clone the index definition.
+        index->reinit_dynamic(
+            this, 
+            index_idx,
+            uniq, 
+            cbegin, 
+            cend);
+            
+        index->indexname = name;
+        
+        bool mightfail = true;
+        
+        //  We have to free that slot if anything fails.
+        try {
+            prow_shape_t newshape = get_minimum_prow_shape();
+            if (newshape.idx_count == index_idx) {
+                newshape.idx_count = (index_idx_t)(newshape.idx_count + 1);
+            }
+            
+            if (!fixed_dropped()) {
+                //  Before we can index fixed rows, we have to create pending objects
+                //  for them.  Explode does this.
+                //  This could throw if there's an allocation failure.
+                explode(prow_shape_t::compute_reserve_shape(newshape));
+            }
+        
+            //  We must always check that the rows are sufficiently large if this
+            //  is a new extremum.
+            bool newlimit = true;
+            for (
+                index_ctx *const*i = indexes_by_position.begin() + index_idx + 1; 
+                i != indexes_by_position.end(); 
+                i++) 
+            {
+                //  Any existing larger index saves us the trouble.
+                if (*i) {
+                    newlimit = false;
+                    break;
+                }
+            }
+            if (newlimit) {
+                //  This could throw if there's an allocation failure.
+                cond_grow_pending_rows(newshape);
+            }
+            
+            //  Now link all the rows.
+            //
+            //  This could throw if the index creates a constraint that's not
+            //  met by existing rows.  If the index  has no uniqueness constraint,
+            //  this should not fail.
+            if (!index->defn.require_unique) {
+                mightfail = false;
+            }
+            index->link_all();
+        } catch (...) {
+            OINKY_ASSERT(mightfail);
+            throw;
+        }
+        
+        //  Now that the index is valid, insert it.
+        indexes_by_position.create(index->index_idx, index);
+
+        mark_ixset_change();
+    }
+};
+
+//  This is the public/user interface to the table_ctx.
+template<typename TABLE_CTX>
+class table_handle_t
+{
+    typedef TABLE_CTX table_ctx;
+    table_ctx *table;
+    
+    typedef typename table_ctx::index_ctx index_ctx;
+    typedef typename table_ctx::column_selector_t column_selector_t;
+    typedef typename table_ctx::indexes_t indexes_t;
+    typedef typename table_ctx::columns_t columns_t;
+    typedef typename table_ctx::safe_itr_t safe_itr_t;
+    typedef typename table_ctx::pending_row_t pending_row_t;
+    typedef typename table_ctx::safe_pending_cursor safe_pending_cursor;
+    typedef typename table_ctx::safe_tbl_cursor_host safe_tbl_cursor_host;
+    
+public:
+    table_handle_t() : table(NULL) {}
+    table_handle_t(table_ctx *_table) : table(_table) {}
+
+    //  This tells if the handle value is uninitialized.  If this returns false,
+    //  it does NOT mean the handle is valid.  It may still be an expired handle
+    //  or just invalid.  But it is a test as to whether it's initialized at all.
+    bool is_null() const { return table == NULL; }
+
+    //###############
+    //  For the C API.  The type is completely opaque, but an equivalent
+    //  handle object can be recovered from it.
+    class raw_handle_t {};
+    raw_handle_t *raw() const { return (raw_handle_t *) table; }
+    table_handle_t(raw_handle_t *_table) : table((table_ctx *) _table) {}
+
+    //###############
+    //  Handle OPS
+    db_string name() const { return table->tablename.as_string(); }
+    uint32 last_colset_change() const { return table->last_colset_change; }
+    uint32 last_ixset_change() const { return table->last_ixset_change; }
+    uint32 last_schema_change() const { 
+        return MAX(last_ixset_change(), last_colset_change()); 
+    }
+    
+    bool table_modified_since(sp_marker_t sp) const { 
+        return table->table_modified_since(sp); 
+    }
+
+    typedef index_handle_t<index_ctx> index_handle;
+    typedef typename column_ctx::column_handle column_handle;
+    typedef typename table_ctx::row_iterator row_iterator;
+    typedef typename index_ctx::iterator index_row_iterator;
+    typedef typename table_ctx::cursor_handle cursor_handle;
+    typedef typename table_ctx::index_positional_itr_t index_positional_itr_t;
+    typedef typename table_ctx::cols_by_name_itr_t cols_by_name_itr_t;
+
+    //  Column selectors choose sets of columns on which to operate on
+    //  (insert/select/etc.)
+    template<typename NAME_ITR_T>
+    column_selector_t make_selector(NAME_ITR_T begin, NAME_ITR_T end) const {
+        return make_selector(simple_sequence<NAME_ITR_T>(begin,end));
+    }
+
+    //  TBD:
+    //  At the moment we return this rather than exposing the constructor
+    //  to the user.  This is more inline with the iterator model.
+    //  It implies the lifetime requirements.  The object is generated
+    //  and therefore owned by the table.
+    template<typename SEQ_T>
+    column_selector_t make_selector(const SEQ_T &cols) const {
+        return column_selector_t(table, cols);
+    }
+    
+    column_selector_t all_columns() const {
+        return column_selector_t::select_all(table);
+    }
+    
+    //  Insert data
+    template<typename VAL_ITR_T>
+    row_iterator insert_row(const column_selector_t &cs, VAL_ITR_T begin, VAL_ITR_T end) const {
+        return insert_row(cs,simple_sequence<VAL_ITR_T>(begin,end));
+    }
+    template<typename SEQ_T>
+    row_iterator insert_row(const column_selector_t &cs, const SEQ_T &seq) const {
+        typename table_ctx::pitr_t pi = table->insert_row(
+            cs, 
+            seq, 
+            table->live_pending.end(),
+            boost::bind(&table_ctx::fill_row_defaults,table,_1));
+        return table->row_iterator_at(pi);
+    }
+
+    //  Update
+    template<typename VAL_ITR_T>
+    void update_row(row_iterator &itr, const column_selector_t &cs, VAL_ITR_T begin, VAL_ITR_T end) const {
+        update_row(itr, cs, simple_sequence<VAL_ITR_T>(begin,end));
+    }
+    template<typename SEQ_T>
+    void update_row(row_iterator &itr, const column_selector_t &cs, const SEQ_T &newrow) const {
+        table->update_row(itr, cs, newrow);
+    }
+
+    template<typename CURSOR, typename VAL_ITR_T>
+    void update_row(const CURSOR &crs, const column_selector_t &cs, VAL_ITR_T begin, VAL_ITR_T end) const {
+        update_row(crs, cs, simple_sequence<VAL_ITR_T>(begin,end));
+    }
+    template<typename CURSOR, typename SEQ_T>
+    void update_row(const CURSOR &crs, const column_selector_t &cs, const SEQ_T &newrow) const {
+
+        row_idx_t fixed = (row_idx_t) -1;
+        pending_row_t *row = NULL;
+        
+        //  This will throw if cursor's target-row has been modified or 
+        //  deleted since the cursor position was last set.
+        crs.unpack_check_active(table, &fixed, &row);
+        
+        if (row) {
+            table->update_dynamic_row(row, cs, newrow);
+        } else {
+            table->update_fixed_row(fixed, cs, newrow);
+        }
+    }
+    
+    //  Erase row
+    void erase(row_iterator &row) const {
+        table->erase(row);
+    }
+    
+    template<typename CURSOR>
+    void erase(const CURSOR &crs) const {
+        row_idx_t fixed = (row_idx_t) -1;
+        pending_row_t *row = NULL;
+        
+        //  This will throw if cursor's target-row has been modified or 
+        //  deleted since the cursor position was last set.
+        crs.unpack_check_active(table, &fixed, &row);
+        
+        if (row) {
+            table->erase_pending(row, true);
+        } else {
+            table->erase_fixed(fixed);
+        }
+    }
+
+    template<typename BASE>
+    class columns_accessor_spec : public BASE
+    {
+        table_ctx *table;
+        using BASE::extract_ctx;
+    public:
+        columns_accessor_spec(table_ctx *_table) : 
+        BASE(_table->columns),
+            table(_table)
+        {}
+        
+        typedef typename BASE::iterator iterator;
+
+        uint32 count() const { return table->cols_by_position.size(); }
+
+        template<typename DEFAULT_VALUE_T>
+        iterator create(const db_string &colname, column_type_code_t _ct, DEFAULT_VALUE_T default_value) {
+            table_column_def def(colname, _ct, variant_cv_t(default_value));
+            create(def);
+            return BASE::find(colname);
+        }
+        
+        iterator create(const table_column_def &def) {
+            create(&def, (&def) + 1);
+            return BASE::find(def.column_name);
+        }
+        
+        template<typename SEQ>
+        void create(const SEQ &seq) { 
+            create(seq.begin(), seq.end()); 
+        }
+        
+        template<typename ITR>
+        void create(const ITR &_begin, const ITR &_end) 
+        {
+            BOOST_STATIC_ASSERT((boost::is_same<
+                table_column_def, 
+                typename boost::iterator_value<ITR>::type>::value));
+                
+            //  How many columns are we adding?  Allocate the context.
+            uint32 bytes = 0, bits = 0, cdelta = 0;
+            for (ITR ci = _begin;ci != _end; ++ci) {
+                cdelta += 1;
+                if (ci->column_type == column_types::Bit) {
+                    bits += 1;
+                } else {
+                    if (ci->column_type > OINKY_VALUE_TYPE_MAX) {
+                        throw_error(invalid_argument());
+                    }
+                    bytes += compute_pending_width(ci->column_type);
+                }
+            }
+            
+            //  Compute the new minimum row shape.
+            prow_shape_t target_shape = table->get_minimum_prow_shape();
+            target_shape.column_bytes += bytes + ((bits + 7)>>3);
+            
+            //  This will just ensure allocation.  It will not reassign anything.
+            table->cols_by_position.reserve(table->cols_by_position.size() + cdelta);
+        
+            //  Grow the pending row objects.  We have to do this regardless,
+            //  since we are less aggressive about reallocating rows than 
+            //  the context map.
+            //
+            //  Do it before calling explode, which could end up creating
+            //  a lot more rows that would then need to be iterated through.
+            table->cond_grow_pending_rows(target_shape);
+                
+            //  Alter-table causes explode.  Do it if we haven't already.
+            table->explode(prow_shape_t::compute_reserve_shape(target_shape));
+            
+            //  Record the current savepoint in case we need to roll back.
+            sp_marker_t sp = table->db->active_sp();
+            
+            //  If there's any chance this can non-atomically fail, then 
+            //  advance the savepoint.  Such is the case if we are creating
+            //  more than one column.
+            if (cdelta > 1) {
+                table->db->new_sp();
+            }
+            
+            //  Save our iterators so we can set default values later.
+            uint32 ccount = 0;
+            column_ctx **newcols = (column_ctx **) alloca(cdelta * sizeof(column_ctx *));
+
+            try {
+                //  Now ready to create columns.
+                for (ITR i = _begin; i != _end; ++i, ++ccount) {
+                    const table_column_def &def(*i);
+
+                    //  Create the column.
+                    iterator colsitr = BASE::create(
+                        def.column_name, 
+                        table->db->active_sp(), 
+                        boost::bind(
+                            &table_ctx::make_column, 
+                            table, 
+                            _1, 
+                            _2, 
+                            def)); 
+                            
+                    newcols[ccount] = extract_ctx(colsitr);
+                }
+                OINKY_ASSERT(ccount == cdelta);
+                
+                //  Now set all the default values.  Everything here is safe
+                //  against exceptions, not that it matters.
+                typename table_ctx::pitr_t ri = table->live_pending.begin();
+                typename table_ctx::pitr_t rend = table->live_pending.end();
+                for (;ri != rend; ++ri) {
+                    OINKY_ASSERT(!ri->ls.is_deleted());
+                    for (uint32 ci = 0; ci < cdelta; ++ci) {
+                        const column_ctx &cc(*newcols[ci]);
+                        ri->set_value(cc, cc.default_value);
+                    }
+                }
+            } catch (...) {
+                table->sp_rollback(sp);
+                throw;
+            }
+            
+            //  At this point we've done everything but update the ordered 
+            //  direct column map.  There was no point in doing it incrementally.
+            //  Easier to just rebuild it now all at once.
+            table->rebuild_cols_by_position();
+        }
+
+        void drop(iterator &itr) 
+        {
+            //  Get the context object.
+            column_ctx *ctx = BASE::extract_ctx(itr);
+            
+            //  Check to see if any indexes reference the column.  If so, we
+            //  can't drop the column.
+            index_positional_itr_t idx = table->indexes_by_position.begin();
+            index_positional_itr_t idxend = table->indexes_by_position.end();
+            for (;idx != idxend; ++idx) {
+                if (!*idx) continue;
+                index_ctx &ix(**idx);
+                
+                const column_ctx *const *i = ix.column_refs;
+                const column_ctx *const *iend = i + ix.defn.col_count;
+                for (;i != iend; ++i) {
+                    if (*i == ctx) {
+                        throw_error(object_still_referenced());
+                    }
+                }
+            }
+            
+            //  Clear to drop.  
+            BASE::drop(itr, table->db->active_sp());
+            table->rebuild_cols_by_position();
+            
+            table->mark_colset_change();
+        }
+    };
+
+    template<typename BASE>
+    class indices_accessor_spec : public BASE
+    {
+        table_ctx *table;
+    public:
+        indices_accessor_spec(table_ctx *_table) : 
+        BASE(_table->indexes),
+            table(_table)
+        {}
+        
+        size_t count() const { return table->indexes_by_position.live_count(); }
+                
+        typedef typename BASE::iterator iterator;
+
+        template<typename ITR_T>
+        iterator create(const db_string &name, index_uniqueness_spec_t uniq, ITR_T cbegin, ITR_T cend) 
+        {
+            BOOST_STATIC_ASSERT((boost::is_same<
+                typename boost::iterator_value<ITR_T>::type, 
+                index_column_def>::value));
+                
+            return BASE::create(
+                name, 
+                table->db->active_sp(), 
+                boost::bind(
+                    boost::type<void>(), 
+                    &table_ctx::template make_index<ITR_T>, 
+                    table, 
+                    _1, 
+                    _2,
+                    uniq,
+                    cbegin, 
+                    cend));
+        }
+        
+        void drop(iterator &itr) 
+        {
+            //  Must do this before we remove it from the context map.
+            index_ctx *ctx = BASE::extract_ctx(itr);
+            BASE::drop(itr, table->db->active_sp());
+            table->indexes_by_position.drop(ctx->index_idx, ctx);
+            ctx->drop(table->db->active_sp());
+            table->mark_ixset_change();
+        }
+    };
+
+    //  Enumerate table metadata
+    typedef typename indexes_t::template set_accessor_t<index_handle, indices_accessor_spec>::type indices_accessor_t;
+    indices_accessor_t indices() const { return indices_accessor_t(table); }
+
+    typedef typename columns_t::template set_accessor_t<column_handle, columns_accessor_spec>::type columns_accessor_t;
+    columns_accessor_t columns() const { return columns_accessor_t(table); }
+
+    //  Enumerate rows.
+    row_iterator rows_begin() const { 
+        return table->rows_begin();
+    }
+    
+    row_iterator rows_end() const { 
+        return table->rows_end();
+    }
+    
+    uint32 row_count() const { 
+        return table->row_count(); 
+    }
+
+    cursor_handle new_cursor(const row_iterator &where) const {
+        if (table != where.table) {
+            //  Invalid iterator, or iterator over a different table.
+            throw_error(invalid_argument());
+        }
+
+        return cursor_handle(safe_tbl_cursor_host(table), make_safe_itr(where));
+    }
+    void delete_cursor(cursor_handle &where) const {
+        where.free();
+    }
+    void move_cursor(cursor_handle &crs, const row_iterator &where) const {
+        if ((table != crs.host.tbl) ||
+            (table != where.table)) 
+        {
+            //  Cursor/Iterator/TbHandle do not match.
+            throw_error(invalid_argument());
+        }
+        
+        crs.iterator() = make_safe_itr(where);
+    }
+private:
+    safe_itr_t make_safe_itr(const row_iterator &where) const 
+    {
+        bool p_bbegin = where.pending_range().before_begin();
+        
+        pending_row_t *p_row = where.pending_range().is_valid() ? 
+            typename table_ctx::pending_to_row()(where.pending()) : 
+            NULL;
+        
+        return safe_itr_t(
+            table, 
+            where.fixed_range(),
+            safe_pending_cursor(safe_tbl_cursor_host(table), p_row, p_bbegin));
+    }
+};
+
+} //namespace Internal
+} //namespace Oinky
+
+
+namespace std
+{
+
+template<class _Traits, class TABLE_CTX> 
+inline std::basic_ostream<char, _Traits>& 
+operator<<(
+    std::basic_ostream<char, _Traits> &os, 
+    const Oinky::Internal::column_selector_template<TABLE_CTX> &selector
+    )
+{
+    selector.format(os);
+    return os;
+}
+
+
+}//namespace std
+