oinky 0.1.0

data/ext/include/oinky/nky_cursor.hpp

@@ -0,0 +1,665 @@
+//  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;
+using namespace Oinky::Utils;
+
+
+//  The row iterator template provides table/select access mechanisms to any
+//  enumerator over selectable rows.
+template<typename TABLE_CTX, typename DERIVED, typename BASE>
+class row_iterator_template : public boost::iterator_adaptor<
+    DERIVED, 
+    BASE,
+    const row_iterator_template<TABLE_CTX,DERIVED,BASE> &,
+    boost::bidirectional_traversal_tag,
+    const row_iterator_template<TABLE_CTX,DERIVED,BASE> &
+    >
+{
+    template<typename DB> friend class table_ctx_t;
+    typedef boost::iterator_adaptor<
+        DERIVED, 
+        BASE,
+        const row_iterator_template<TABLE_CTX,DERIVED,BASE> &,
+        boost::bidirectional_traversal_tag,
+        const row_iterator_template<TABLE_CTX,DERIVED,BASE> &
+        > base_t;
+        
+    typedef row_iterator_template<TABLE_CTX,DERIVED,BASE> this_t;
+    typedef pending_row<TABLE_CTX> pending_row_t;
+    typedef column_selector_template<TABLE_CTX> column_selector_t;
+    typedef TABLE_CTX table_ctx;
+    
+    friend class boost::iterator_core_access;
+    
+protected:
+    struct select_accessor_data
+    {
+        row_idx_t rowkey;
+        const pending_row_t *prow;
+        const table_ctx *table;
+
+        select_accessor_data(
+            row_idx_t _rowkey,
+            const pending_row_t *_prow,
+            const table_ctx *_table) :
+        rowkey(_rowkey),
+            prow(_prow),
+            table(_table)
+        {}
+    };
+private:
+    struct select_accessor_base
+    {
+        const column_selector_t &selector;
+        select_accessor_data data;
+    public:
+        select_accessor_base(
+            const column_selector_t &_selector,
+            const select_accessor_data _data) :
+        selector(_selector),
+            data(_data)
+        {}
+        
+        uint32 column_count() const { return selector.column_count(); }
+
+        //  Parameters are a column definition and a value
+        template<typename FN>
+        void each_column_value(FN fn) const{
+            if (data.prow) {
+                data.prow->each_column_value(selector, fn);
+            } else {
+                data.table->fixed.each_column_value(selector, data.rowkey, fn);
+            }
+        }
+    };
+
+    const this_t &dereference() const { 
+        return *this;
+    }
+    
+public:
+    bool at_end() const { return base_t::base().at_end(); }
+    bool before_begin() const { return base_t::base().before_begin(); }
+
+    row_iterator_template() {}
+    row_iterator_template(const BASE &val) : base_t(val) {}
+
+    typedef multicolumn_value_accessor<select_accessor_base> select_accessor;
+
+    select_accessor select(const column_selector_t &cs) const {
+        const DERIVED *dp = (const DERIVED *) this;
+        return select_accessor(
+            select_accessor_base(
+                cs,
+                dp->get_selector_data()));
+    }
+    
+    bool operator<(const this_t &other) const { return base_t::base() < other.base(); }
+    bool operator>(const this_t &other) const { return base_t::base() > other.base(); }
+    bool operator<=(const this_t &other) const { return base_t::base() <= other.base(); }
+    bool operator>=(const this_t &other) const { return base_t::base() >= other.base(); }
+};
+    
+//
+//  It is an axiom of the programming model that all objects exposed to
+//  the user (other than the database handle itself) have trivial 
+//  destructors.  This fits well with the C++/STL container paradigm
+//  where the iterators have trivial destructors, and do not reference
+//  the container itself.  The caller must be responsible enough not to
+//  use expired iterators, but the implementation does not force the caller
+//  to destroy iterators prior to the container.
+//
+//  The cursor concept is a deviation from the C++/STL iterator concept 
+//  in that it is safer.  While a savepoint rollback, alter-table, 
+//  row-delete, row-update, create-index, etc. can all invalidate an 
+//  iterator, the cursor will survive.  Only database unmount (handle 
+//  destruction) will invalidate the cursor.
+//
+//  This simplicity requires a bit of internal referencing, managed by 
+//  splitting the cursor into an internal and external part.  The external 
+//  part behaves like a handle.  It's a pointer to the internal cursor 
+//  object.  Copying the handle does not clone the cursor.  To clone the 
+//  cursor, the handle's clone method must be invoked, which makes a copy
+//  of the internal cursor object and returns a new pointer to it.
+//
+//  These cursor objects are linked together among cursors over the same
+//  parent (index/table).  They are linked on allocation and unlinked
+//  either when the cursor gets deleted or when the parent gets deleted.
+//  This is a simpler alternative to refcounting the parent, as the lifetime
+//  of parent objects (what with create/drop/undrop) is complex enough
+//  as it is.
+//
+template<typename SAFE_ITR>
+struct cursor_internal_t : 
+    boost::intrusive::list_base_hook<
+        boost::intrusive::link_mode<
+            boost::intrusive::safe_link
+        > >
+{
+    typedef SAFE_ITR safe_itr_t;
+    
+    safe_itr_t itr;
+    uint64 cookie;
+
+    cursor_internal_t(const safe_itr_t &_itr) : itr(_itr) {}
+
+    //  This is called by the host when it invalides its active cursors.
+    void invalidate() {
+        cookie = 0;
+    }
+    
+    ~cursor_internal_t() 
+    {
+        invalidate();
+        
+        //  We should have already been unlinked from our host.
+        //  This method is on the safe-mode hook from which we are derived.
+        OINKY_ASSERT(!is_linked());
+        
+        // ~itr does the dereferencing of the pending_row
+    }
+};
+
+template<typename INTERNAL_T, typename HOST_T>
+class cursor_handle_t
+{
+    template<typename TABLE_CTX> friend class index_ctx_t;
+    template<typename INDEX_CTX> friend class index_handle_t;
+    template<typename TABLE_CTX> friend class table_handle_t;
+    template<typename DB> friend class table_ctx_t;
+    
+    typedef HOST_T host_t;
+    typedef INTERNAL_T cursor_internal_t;
+    typedef typename cursor_internal_t::safe_itr_t safe_itr_t;
+    typedef cursor_handle_t<INTERNAL_T,HOST_T> cursor_handle;
+    
+    cursor_internal_t *cursor;
+    host_t host;
+    safe_itr_t *itr;
+
+    static uint64 cookie_value() { return 0xe3c1290b4a75f6d8ull; }
+
+    cursor_handle_t(cursor_internal_t *_cursor) :
+    cursor(_cursor),
+        host(_cursor->itr.pending().host),
+        itr(&_cursor->itr)
+    {
+    }
+
+    cursor_handle_t(const host_t &_host, const safe_itr_t &where) :
+    host(_host)
+    {
+        //  Convert the unsafe pending iterator type to a safe one.
+        cursor = (cursor_internal_t *) host.allocator().malloc(sizeof(cursor_internal_t));
+        ::new(cursor) cursor_internal_t(where);
+        OINKY_ASSERT(cursor->itr.pending().host == host);
+        host.link_cursor(cursor);
+        cursor->cookie = cookie_value();
+        itr = &cursor->itr;
+    }
+public:
+    //###############
+    //  For the C API.  The type is completely opaque, but an equivalent
+    //  handle object can be recovered from it.
+    //
+    //  The RAW transformation follows the same pattern as that for table/index 
+    //  handles.  The difference is that reconstruction of a bad handle
+    //  can raise, whereas reconstruction of a bad table handle won't raise
+    //  until the reconstructed handle is used.
+    class raw_handle_t {};
+    raw_handle_t *raw() const { return (raw_handle_t *) cursor; }
+    cursor_handle_t(raw_handle_t *_raw) {
+        //  Just forward to the normal constructor.
+        *this = cursor_handle_t((cursor_internal_t *)_raw);
+    }
+
+private:    
+    void check_valid() const {
+        host.check_state();
+        
+        if (!itr || !cursor ||
+            (cursor->cookie != cookie_value()) ||
+            (host != cursor->itr.pending().host)) 
+        {
+            //  Invalid cursor.
+            throw_error(invalid_argument());
+        }
+    }
+    
+    template<typename TABLE_CTX, typename PROW>
+    void unpack_check_active(const TABLE_CTX *table, row_idx_t *fixed, PROW **row) const
+    {
+        check_valid();
+        
+        if (!valid_data() || (host.table() != table)) {
+            throw_error(invalid_argument());
+        }        
+        OINKY_ASSERT(itr == &cursor->itr);
+        
+        if (cursor->itr.pending_active()) {
+            PROW *rtmp = cursor->itr.pending().to_row();
+            *row = rtmp;
+            *fixed = (row_idx_t) -1;
+            
+            if (rtmp->is_inactive()) {
+                //  The cursor's target-row has been modified or deleted since 
+                //  the cursor position was last set.
+                throw_error(object_deleted());
+            }
+        } else if (cursor->itr.fixed_active()) {
+            *row = NULL;
+            *fixed = *cursor->itr.fixed();
+            
+            if (table->is_deleted(*fixed)) {
+                //  The cursor's target-row has been modified or deleted since 
+                //  the cursor position was last set.
+                throw_error(object_deleted());
+            }
+        } else {
+            //   Cursor is not even valid.
+            throw_error(invalid_argument());
+        }
+    }
+    
+    //  See notes before calling this method.  Free is implicit when the 
+    //  DB is destroyed.  Calling free twice is bad.  Calling it after 
+    //  destroying the DB object is equivalently bad.  An app really
+    //  only need call it on DB instances that will be very long lived and
+    //  instantiate many cursors.
+    void free()
+    {
+        check_valid();
+        host.unlink_cursor(cursor);
+        cursor->~cursor_internal_t();
+        host.allocator().free(cursor);
+        cursor = NULL;
+        host = host_t();
+        itr = NULL;
+    }
+public:
+    //  Copy-construct the internal cursor object (which makes a deep copy)
+    //  and return a new reference to it.
+    cursor_handle clone() const {
+        check_valid();
+        cursor_internal_t *crs = (cursor_internal_t *) host.allocator().malloc(sizeof(cursor_internal_t));
+        ::new(crs) cursor_internal_t(*cursor);
+        cursor_handle nh(crs);
+        nh.host.link_cursor(crs);
+        return nh;
+    }
+    
+    //  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 cursor == NULL; }
+
+    cursor_handle_t() : cursor(NULL), itr(NULL) {}
+        
+    bool seek_next() {
+        check_valid();
+        if (!itr->at_end()) {
+            ++(*itr);
+        }
+        return valid_data();
+    }
+    
+    bool seek_prev() {
+        check_valid();
+        if (!itr->before_begin()) {
+            --(*itr);
+        }
+        return valid_data();
+    }
+    
+    safe_itr_t &iterator() { return *itr; }
+        
+    //  Is the cursor referencing valid data?
+    //  Note that this method will throw if the cursor itself is bad.
+    //  (cursor erased/index dropped).
+    bool valid_data() const {
+        check_valid();
+        return itr->fixed_active() || itr->pending_active();
+    }
+    
+    bool at_end() const { 
+        check_valid();
+        return itr->at_end();
+    }
+    bool before_begin() const { 
+        check_valid();
+        return itr->before_begin();
+    }
+    
+    typedef typename safe_itr_t::select_accessor select_accessor;
+
+    template<typename SELECTOR>
+    select_accessor select(const SELECTOR &cs) const {
+        check_valid();
+        if (!valid_data() || (host.table() != cs.table)) {
+            throw_error(invalid_argument());
+        }        
+        return itr->select(cs);
+    }
+    
+    int compare_to(const cursor_handle &other) const {
+        check_valid();
+        other.check_valid();
+        
+        if (host != other.host) {
+            //  Can't compare cursors over different indices.
+            //
+            //  The user may intend to compare selects over different
+            //  indices, which is reasonable.
+            //
+            //  t1i1.select(table1.select("foo")).compare_to(t2i4.select("bar"))
+            //  --compares the column "foo" at cursor/iterator t1i1 to 
+            //  column "bar" at cursor/iterator t2i4
+            //
+            throw_error(invalid_argument());
+        }
+        return itr->compare_to(*other.itr);
+    }
+    
+    bool operator==(const cursor_handle &other) const { return compare_to(other) == 0; }
+    bool operator!=(const cursor_handle &other) const { return compare_to(other) != 0; }
+    bool operator<(const cursor_handle &other) const { return compare_to(other) < 0; }
+    bool operator>(const cursor_handle &other) const { return compare_to(other) > 0; }
+    bool operator<=(const cursor_handle &other) const { return compare_to(other) <= 0; }
+    bool operator>=(const cursor_handle &other) const { return compare_to(other) >= 0; }
+};
+    
+template<typename TABLE_CTX, typename FITR, typename FRANGE, typename PITR, typename PRANGE, typename COMPARE, typename TO_ROW>
+struct iterator_builder
+{
+    typedef TABLE_CTX table_ctx;
+    
+    class iterator_base : public merge_iterator_template<
+        iterator_base, //derived
+        int, //value
+        FRANGE, 
+        PRANGE, 
+        COMPARE >
+    {
+        typedef merge_iterator_template<
+            iterator_base, //derived
+            int, //value
+            FRANGE, 
+            PRANGE, 
+            COMPARE > base_t;
+        
+        friend class boost::iterator_core_access;
+        
+        void skip_deleted()
+        {
+            while (base_t::left_active() && base_t::left().i().is_deleted()) {
+                OINKY_ASSERT(!base_t::right_active());
+                base_t::increment();
+            }
+        }
+        
+        //  Identical to base items, but must skip fixed entries (without
+        //  skipping too far).
+        void increment()
+        {
+            base_t::increment();
+            skip_deleted();
+        }
+        void decrement()
+        {
+            base_t::decrement();
+            while (base_t::left_active() && base_t::left().i().is_deleted()) {
+                OINKY_ASSERT(!base_t::right_active());
+                base_t::decrement();
+            }
+        }
+        
+        //  Irrelevant.
+        int dereference() const { return 0; }
+    public:
+        iterator_base(
+            const FRANGE &_l,
+            const PRANGE &_r) :
+        base_t(_l,_r)
+        {
+            skip_deleted();
+        }
+
+        iterator_base() {}
+    };
+    
+    class iterator : public row_iterator_template<table_ctx, iterator, iterator_base>
+    {
+        friend class boost::iterator_core_access;
+        friend class index_ctx_t<table_ctx>;
+        template<typename INDEX_CTX> friend class index_handle_t;
+        template<typename CRS, typename HOST> friend class cursor_handle_t;
+        template<typename DB> friend class table_ctx_t;
+        
+        typedef row_iterator_template<table_ctx, iterator, iterator_base> base_t;
+        friend class row_iterator_template<table_ctx, iterator, iterator_base>;
+        friend class table_handle_t<table_ctx>;
+        
+        TABLE_CTX *table;
+        iterator(TABLE_CTX *_table, const iterator_base &itr) : base_t(itr), table(_table) {}
+        
+        iterator(
+            TABLE_CTX *_table, 
+            const FRANGE &_l,
+            const PRANGE &_r) :
+        base_t(iterator_base(_l,_r)),
+            table(_table)
+        {}
+
+    public:
+        iterator() : table(NULL) {}
+
+    private:
+        template<typename X,typename SCHEME> friend class ::Oinky::Serialization::Serializer;
+
+        const FRANGE &fixed_range() const { return base_t::base().left(); }
+        const FITR &fixed() const { return fixed_range().i(); }
+        const PRANGE &pending_range() const { return base_t::base().right(); }
+        const PITR &pending() const { return base_t::base().right().i(); }
+
+        bool fixed_active() const { return base_t::base().left_active(); }
+        bool pending_active() const { return base_t::base().right_active(); }
+        
+        int compare_to(const iterator &other) const {
+            return base_t::base().compare_to(other.base_t::base());
+        }
+    
+        typedef typename base_t::select_accessor_data select_accessor_data;
+        select_accessor_data get_selector_data() const {
+            bool fa = fixed_active();
+            bool pa = pending_active();
+            if (!fa && !pa) {
+                //  Selecting on invalid iterator.
+                throw_error(invalid_argument());
+            }
+            
+            return select_accessor_data(
+                fa ? *fixed() : (row_idx_t) -1,
+                pa ? TO_ROW()(pending()) : NULL,
+                table);
+        }
+    };
+};
+
+//  This is a safe iterator over the pending rows.  It can traverse 
+//  an index even when the table is being modified.
+template<typename PROW, typename HOSTOPS>
+class safe_pending_cursor_t
+{
+    PROW *row;
+public:
+    typedef HOSTOPS host_t;
+    HOSTOPS host;
+private:
+    bool bbegin;
+    
+    static void update_row_reference(PROW *old, PROW *nr)
+    {
+        OINKY_ASSERT((old != nr) || !old);
+        if (nr) {
+            nr->cursor_reference();
+        }
+        if (old) {
+            old->cursor_dereference();                            
+        }
+    }
+    
+public:
+    safe_pending_cursor_t() : row(NULL), bbegin(false) {}
+
+    safe_pending_cursor_t(const safe_pending_cursor_t &src) :
+    row(src.row),
+        host(src.host),
+        bbegin(src.bbegin)
+    {
+        if (row) {
+            update_row_reference(NULL, row);
+        }
+    }
+    
+    safe_pending_cursor_t &operator=(const safe_pending_cursor_t &src) {
+        if (&src == this) {
+            return *this;
+        }
+        if (row != src.row) {
+            update_row_reference(row, src.row);
+        }
+        row = src.row;
+        host = src.host;
+        bbegin = src.bbegin;
+        return *this;
+    }
+    
+    safe_pending_cursor_t(const host_t &_host, PROW *_row, bool _bbegin) :
+    row(_row),
+        host(_host),
+        bbegin(_bbegin)
+    {
+        OINKY_ASSERT(!bbegin || !row);
+        update_row_reference(NULL, row);
+    }
+    
+    ~safe_pending_cursor_t() {
+        if (row) {
+            update_row_reference(row, NULL);
+        }
+        row = NULL;
+    }
+    
+    bool before_begin() const { return bbegin; }
+    bool at_end() const { return !bbegin && !row; }
+    bool is_valid() const { return row != NULL; }
+    
+    void decrement()
+    {
+        //  First check that the index still exists.
+        host.check_state();
+        
+        //  Already invalid.  No-op.
+        if (bbegin) {
+            return;
+        }
+        
+        //  At end.  Find last.
+        if (!row) {
+find_last:            
+            OINKY_ASSERT(at_end());
+            PROW *new_row = host.seek_prev(NULL);
+            if (!new_row) {
+                bbegin = true;
+            } else {
+                update_row_reference(NULL, new_row);
+                row = new_row;
+            }
+            return;
+        }
+
+        //  We're pointing to a real row, though it may be deleted.
+        host.assert_row_valid(row);
+        
+        //  See comment in increment()
+        if (row->is_inactive()) {
+            //  Seek using the lower bound.
+            PROW *new_row = host.seek_pending(true, row);
+            if (!new_row) {
+                update_row_reference(row, NULL);
+                row = NULL;
+                goto find_last;
+            }
+        }
+        //  Seek one previous.  (result might be NULL)
+        PROW *new_row = host.seek_prev(row);
+        update_row_reference(row, new_row);
+        row = new_row;
+        if (!row) {
+            bbegin = true;
+        }
+    }
+    void increment()
+    {
+        //  First check that the index still exists.
+        host.check_state();
+        
+        //  Seek begin.
+        if (bbegin) {
+            bbegin = false;
+            row = host.seek_next(NULL);
+            if (row) {
+                update_row_reference(NULL, row);
+            }
+            return;
+        }
+
+        //  Already at end.  No-op.
+        if (at_end()) {
+            return;
+        }
+        
+        //  Now it's a real increment.
+        host.assert_row_valid(row);
+        
+        //  If the row was deleted since we last iterated to it, then
+        //  we need to re-seek.  Note that if the row gets updated while
+        //  it has a cursor on it, we perform the update by delete/insert
+        //  rather than rewriting any values.  This allows cursors to
+        //  maintain consistent state until they are moved.
+        //
+        //  Note that we check if it's deleted, not whether it's pending
+        //  destruction.  Deletion means it out of the live tree, out of
+        //  sequence.  It may not yet be pending destruction.
+        PROW *new_row;
+        if (row->is_inactive()) {
+            //  Seek using the upper bound.
+            new_row = host.seek_pending(false, row);
+        } else {
+            new_row = host.seek_next(row);
+        }
+        update_row_reference(row, new_row);
+        row = new_row;
+    }
+    
+    const safe_pending_cursor_t &i() const {
+        return *this;
+    }
+    
+    PROW *operator->() const {
+        return row;
+    }
+    
+    PROW *to_row() const { return row; }
+};//safe_pending_cursor_t
+
+} //namespace Internal
+} //namespace Oinky
+