core/Lucy/Store/Lock.cfh

/* Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

parcel Lucy;

/**
 * Abstract class representing an interprocess mutex lock.
 *
 * The Lock class produces an interprocess mutex lock.  The default subclass
 * uses dot-lock files, but alternative implementations are possible.
 *
 * Each lock must have a name which is unique per resource to be locked.  Each
 * lock also has a "host" id which should be unique per machine; it is used to
 * help clear away stale locks.
 */

abstract class Lucy::Store::Lock inherits Clownfish::Obj {

    Folder      *folder;
    String      *name;
    int32_t      timeout;
    int32_t      interval;

    /** Abstract initializer.
     *
     * @param folder A Folder.
     * @param name String identifying the resource to be locked, which must
     * consist solely of characters matching [-_.A-Za-z0-9].
     * @param host A unique per-machine identifier.
     * @param timeout Time in milliseconds to keep retrying before abandoning
     * the attempt to obtain a lock.
     * @param interval Time in milliseconds between retries.
     */
    public inert Lock*
    init(Lock *self, Folder *folder, String *name, int32_t timeout = 0,
         int32_t interval = 100);

    inert bool
    make_lock_dir(Folder *folder);

    /** Call [](.Request_Shared) once per `interval` until [](.Request_Shared)
     * returns success or the `timeout` has been reached.
     *
     * @return true on success, false on failure (sets the global error object
     * returned by [](cfish:cfish.Err.get_error)).
     */
    public bool
    Obtain_Shared(Lock *self);

    /** Call [](.Request_Exclusive) once per `interval` until
     * [](.Request_Exclusive) returns success or the `timeout` has been
     * reached.
     *
     * @return true on success, false on failure (sets the global error object
     * returned by [](cfish:cfish.Err.get_error)).
     */
    public bool
    Obtain_Exclusive(Lock *self);

    /** Make one attempt to acquire a shared lock.
     *
     * [](.Request_Shared) should not fail if another shared lock is held
     * against the resource identified by `name` (though it might fail for
     * other reasons).
     *
     * @return true on success, false on failure (sets the global error object
     * returned by [](cfish:cfish.Err.get_error)).
     */
    public abstract bool
    Request_Shared(Lock *self);

    /** Make one attempt to acquire an exclusive lock.
     *
     * Other locks should cause [](.Request_Exclusive) to fail.
     *
     * @return true on success, false on failure (sets the global error object
     * returned by [](cfish:cfish.Err.get_error)).
     */
    public abstract bool
    Request_Exclusive(Lock *self);

    /** Release the lock. Locks are always released by the destructor.
     */
    public abstract void
    Release(Lock *self);

    public void
    Destroy(Lock *self);
}

/** Lock exception.
 *
 * LockErr is a subclass of [Err](cfish:cfish.Err) which indicates
 * that a file locking problem occurred.
 */
public class Lucy::Store::LockErr inherits Clownfish::Err {

    inert incremented LockErr*
    new(String *message);

    inert LockErr*
    init(LockErr *self, String *message);
}