The PoolScan Class

An application scans a pool by creating a PoolScan object. PoolScan objects are transient C++ objects, not persistent Shore objects. A PoolScan object can be in one of two states: open or closed. A scan must be opened inside a transaction, and can only be used inside the transaction in which it was opened. Once a scan is opened, it stays open until it is explicitly closed, or until the scan object is destroyed, or the transaction terminates. In particular, the scan object remains open even after the end of the scan has been reached or an error has occurred.

The public interface to the PoolScan class is

    class PoolScan {
     public:
        PoolScan();
        PoolScan(const char *path);
        PoolScan(const ref<Pool> pool);

        shrc open(const char *path);
        shrc open(const ref<Pool> pool);

        shrc next(ref<any> &ref, bool fetch = false, LockMode mode = SH);

        bool is_open();
        shrc rc();
        int operator==(shrc rc);
        int operator!=(shrc rc);

        shrc close();
        ~PoolScan();
    };

PoolScan()

is the default constructor. The resulting PoolScan object is in the closed state. It may be opened by the open member function.

PoolScan(const char *path)

PoolScan(const ref<Pool> pool)

These constructors invoke the corresponding versions of the open member function. The caller should whether the open operation was successful by calling is_open() or by testing the return code with rc(), operator==(), or operator!=().

shrc open(const char *pool)

shrc open(const ref<Pool> pool)

The pool argument should be the pathname of a valid directory in the Shore filesystem namespace or a reference to a Pool object, and the PoolScan object should be in the closed state. The caller must have (at least) read permission for the indicated pool and must have a transaction open. Upon successful completion, RCOK is returned. Any other return value indicates an error condition.

shrc next(ref<any> &ref, bool fetch = false, LockMode mode = SH)

returns a reference to the next object in the pool (if the scan has just been opened, then it returns the first object in the pool). Objects are returned in apparently random order, but each object is returned exactly once by a scan. If fetch is true, the object will be fetched into the object cache, and a lock will be obtained on the object in the mode indicated by mode, if such a lock is not already held by the transaction. If fetch is false (the default), mode is ignored and the object is not fetched from the server.

The return value of next is RCOK if there was a next object in the scan. If an attempt is made to go beyond the end of the scan (i.e., a call to next is made after the last object in the scan has already been returned), then the return code will be OC_EndOfScan. Any other return code indicates an error condition.

bool is_open()

indicates whether the scan is open or closed. Note that the scan remains open after retrieving the last entry.

shrc rc()

returns the return code generated by the last operation (open or next).

int operator==(shrc rc)

int operator!=(shrc rc)

These operators provide a convenient way to check the status of the scan. For example, applications can say if (scan == RCOK) ....

shrc close()

closes the scan object. Closing a scan object releases any resources associated with the scan in both the server and client processes (such as the scan buffer). It also allows the scan object to be reused. The scan is closed implicitly when the PoolScan object is destroyed (either via operator delete or when the DirScan object goes out of scope), or when the transaction in which the scan was opened terminates.

~PoolScan()

The PoolScan destructor closes the scan object if it is open.