A Container contains a contigious address space of pages, the pages start at page number Container.FIRST_PAGE_NUMBER and are numbered sequentially. The page size is set at addContainer() time. RESOLVE: this style of coding is not currently enforced If the caller calls getPage (or one of its variants) more than once on the same page, the caller must call unlatch a corresponding number of times in order to ensure that the page is latched. For example:
Container c; Page p1 = c.getPage(Container.FIRST_PAGE_NUMBER); Page p2 = c.getPage(Container.FIRST_PAGE_NUMBER); p1.unlatch(); -- Page is still latched. p2.unlatch(); -- Page is now unlatched.
There is no restriction on the order in which latching and unlatching is done. In the example, p1 could have been unlatched after p2 with no ill effects.
Open container modes ContainerHandle.MODE are used to open or create the container. Unlike TableProperties, MODEs are not permanantely associated with the container, it is effective only for the lifetime of the containerHandle itself.
A container may use any of these mode flags when it is opened.
- MODE_READONLY - Open the container in read only mode.
- MODE_FORUPDATE - Open the container in update mode, if the underlying storage does not allow updates then the container will be opned in read only mode.
- MODE_UNLOGGED - If Unset, any changes to the container are logged. If set, any user changes to the container are unlogged. It is guaranteed at commit time that all changes made during the transaction will have been flushed to disk. Using this mode automatically opens the container in container locking, isolation 3 level. The state of the container following an abort or any type of rollback is unspecified.
- MODE_CREATE_UNLOGGED - If set, not only are user changes to the container are unlogged, page allocations are also unlogged. This MODE is only useful for container is created in the same statement and no change on the container (other than the create) is ever logged. The difference between MODE_UNLOGGED and MODE_CREATE_UNLOGGED is that page allocation is also unlogged and commit of nested transaction will not cause the container to be forced from the cache. Unlike MODE_UNLOGGED, MODE_CREATE_UNLOGGED does not force the cache. It is up to the client of raw store to force the cache at the appropriate time - this allows a statement to create and open the container serveral times for bulk loading without logging or doing any synchronous I/O.
- MODE_LOCK_NOWAIT - if set, then don't wait for the container lock, else wait for the container lock. This flag only dictates whether the lock should be waited for or not. After the container is successfully opened, whether this bit is set or not has no effect on the container handle.
If neither or both of the {MODE_READONLY, MODE_FORUPDATE} modes are specified then the behaviour of the container is unspecified.
MODE_UNLOGGED must be set for MODE_CREATE_UNLOGGED to be set.
Temporary Containers
If when creating a container the segment used is ContainerHandle.TEMPORARY_SEGMENT then the container is a temporary container. Temporary containers are not logged or locked and do not live across re-boots of the system. In addition any abort or rollback including rollbacks to savepoints truncate the container if it has been opened for update since the last commit or abort. Temporary containers are private to a transaction and must only be used a single thread within the transaction at any time, these restrictions are not currently enforced.
When opening a temporary container for update access these additional mode flags may be used
- MODE_TRUNCATE_ON_COMMIT - At commit/abort time container is truncated.
- MODE_DROP_ON_COMMIT - At commit/abort time the container is dropped.
- MODE_TEMP_IS_KEPT - At commit/abort time the container is kept around.
If a temporary container is opened multiple times in the same transaction with different modes then the most severe mode is used, ie. none < truncate on commit < drop on commit. The MODE_UNLOGGED, MODE_CREAT_UNLOGGED flags are ignored when opening a temporary container, not logged is always assumed.