1:  2:  3:  4:  5:  6:  7:  8:  9: 10: 11: 12: 13: 14: 15: 16: 17: 18: 19: 20: 21: 22: 23: 24: 25: 26: 27: 28: 29: 30: 31: 32: 33: 34: 35: 36: 37: 38: 39: 40: 41: 42: 43: 44: 45: 46: 47: 48: 49: 50: 51: 52: 53: 54: 55: 56: 57: 58: 59: 60: 61: 62: 63: 64: 65: 66: 67: 68: 69: 70: 71: 72: 73: 74: 75: 76: 77: 78: 79: 80: 81: 82: 83: 84: 85: 86: 87: 88: 89: 90: 91: 

<?php

namespace bandwidthThrottle\tokenBucket\storage;

use malkusch\lock\mutex\Mutex;
use bandwidthThrottle\tokenBucket\storage\scope\GlobalScope;
use bandwidthThrottle\tokenBucket\storage\scope\SessionScope;
use bandwidthThrottle\tokenBucket\storage\scope\RequestScope;

/**
 * Token storage.
 *
 * The storage determines the scope for the token bucket. It therefore
 * implements one of the *Scope marker interfaces:
 *
 * - {@link RequestScope}: The bucket is shared only within one request.
 * - {@link SessionScope}: The bucket is shared between requests of one session.
 * - {@link GlobalScope}: The bucket is shared among all processes.
 *
 * @author Markus Malkusch <markus@malkusch.de>
 * @link bitcoin:1335STSwu9hST4vcMRppEPgENMHD2r1REK Donations
 * @license WTFPL
 */
interface Storage
{
    
    /**
     * Returns the Mutex for this storage.
     *
     * @return Mutex The mutex.
     * @internal
     */
    public function getMutex();
    
    /**
     * Returns if the storage was already bootstrapped.
     *
     * @return bool True if the storage was already bootstrapped.
     * @throws StorageException Checking the state of the storage failed.
     * @internal
     */
    public function isBootstrapped();
    
    /**
     * Bootstraps the storage.
     *
     * @param double $microtime The timestamp.
     * @throws StorageException Bootstrapping failed.
     * @internal
     */
    public function bootstrap($microtime);
    
    /**
     * Removes the storage.
     *
     * After a storage was removed you should not use that object anymore.
     * The only defined methods after that operations are isBootstrapped()
     * and bootstrap(). A call to bootstrap() results in a defined object
     * again.
     *
     * @throws StorageException Cleaning failed.
     * @internal
     */
    public function remove();
    
    /**
     * Stores a timestamp.
     *
     * @param double $microtime The timestamp.
     * @throws StorageException Writing to the storage failed.
     * @internal
     */
    public function setMicrotime($microtime);

    /**
     * Indicates, that there won't be any change within this transaction.
     *
     * @internal
     */
    public function letMicrotimeUnchanged();

    /**
     * Returns the stored timestamp.
     *
     * @return double The timestamp.
     * @throws StorageException Reading from the storage failed.
     * @internal
     */
    public function getMicrotime();
}