hadoop-common-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apache Wiki <wikidi...@apache.org>
Subject [Lucene-hadoop Wiki] Update of "DistributedLockServer" by JimKellerman
Date Thu, 01 Feb 2007 03:17:04 GMT
Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Lucene-hadoop Wiki" for change notification.

The following page has been changed by JimKellerman:
http://wiki.apache.org/lucene-hadoop/DistributedLockServer

New page:
##language:en
#pragma section-numbers off

= "Chubby"-like distributed lock service for Hadoop =

== Background ==

Google's [http://labs.google.com/papers/chubby.html Chubby],
a distributed lock manager, is useful for multiple applications requiring distributed locking.

Many of Google's systems require distributed locking. The [http://labs.google.com/papers/gfs.html
Google File System (GFS)], and [http://labs.google.com/papers/bigtable.html Bigtable structured
storage system] are but two examples.

While Hadoop's HDFS has an internal locking mechanism, a general purpose distributed lock
manager would be of use both by Hadoop itself and by ["Hbase"] structured data storage system
at a minimum.

The availability of a distributed lock manager would make it much easier to implement redundant
name nodes in Hadoop.

== Overview ==

 * Distributed Lock Service
 * Provides a namespace of directories and small files
 * Reads and writes to a file are atomic
 * Locking
  * Both directories and files can be used as locks
 * Chubby client maintains a "session" with a Chubby service, which expires if it is unable
to renew it's session lease with ''SessionTimeout'' seconds.
 * Chubby client provides consistent caching of Chubby files

== Applications ==

 * Mediate multiple name nodes and name node failover
 * Provide locking services needed by the ["Hbase"] project

== Lock Service APIs ==

The ["Hbase"]  working group has done some preliminary analysis of Google's Chubby and proposes
(as a starting point) the following distributed lock service client API. There are three interfaces
that comprise this API. The first is the main client API, the second is an interface for event
handlers and the third describes the meta data that is stored for each chubby object.

=== Client API ===

{{{
package org.apache.hbase.lockserver.client;

import java.util.Map;

public interface LockserverClient {

  /** Maximum value for lock delay in open() */
  public static final int MAX_LOCK_DELAY = 60 * 1000;   // one minute
  /** Minimum value for lock delay in open() */
  public static final int MIN_LOCK_DELAY = 2 * 1000;    // two seconds
  
  /**
   * Open modes. May be OR'd together
   */
  /** Open read-only no lock */
  public static final int MODE_READONLY = 1;
  /** Open for writing and locking */
  public static final int MODE_WRITE_AND_LOCK = 2;
  /** Open to change ACL */
  public static final int MODE_SETACL = 4;
  /** Create if does not exist */
  public static final int MODE_CREATE = 8;
  /** Create only if does exist */
  public static final int MODE_MUST_CREATE = 16;
  /**
   * Opens the specified path with the specified mode.
   * @param path
   * @param mode - file open mode above
   * @param lockDelay - time for lock server to wait before releasing lock if
   *                    it can no longer communicate with the client 
   *                    (milliseconds). If zero is specified MIN_LOCK_DELAY is assumed.
   */
  public void open(String path, int mode, int lockDelay);
  
  /**
   * Event types client can register for.
   * Values may be OR'd together.
   */
  /** Contents of node changed */
  public static final int EVENT_CONTENTS = 1;
  /** Child node added */
  public static final int EVENT_CHILD_ADDED = 2;
  /** Child node removed */
  public static final int EVENT_CHILD_REMOVED = 4;
  /** Child node modified */
  public static final int EVENT_CHILD_MODIFIED = 8;
  /** Master lock server failed over */
  public static final int EVENT_MASTER_FAILOVER = 16;
  /** Unable to communicate with lock server - session in jeopardy */
  public static final int EVENT_HANDLE_WARNING = 32;
  /** Communicated with lock server before time out - session safe */
  public static final int EVENT_HANDLE_SAFE = 64;
  /** Unable to communicate with lock server - session invalid */
  public static final int EVENT_HANDLE_EXPIRED = 128;
  /**
   * Register to receive lock server events
   * @param handler - event handler object
   * @param eventMask -  mask of desired event types
   */
  public void setEventHandler(LockEventHandler handler, int eventMask);

  /** Terminates session. Releases allocated resources. */
  public void close();
  
  /** Terminates session. Does not deallocate resources */
  public void poison();
  
  /** Returns the contents of the node (files only) */
  public byte[] getContents();
  
  /**
   * Sets the contents of the node (files only)
   * @param contents
   */
  public void setContents(byte[] contents);
  
  /**
   * Changes the specified ACLs for the node.
   * Note that any of the values may be specified as null in which case they
   * are not changed.
   * @param read - read ACL
   * @param write - write ACL
   * @param control - change ACL
   */
  public void setAcl(String read, String write, String control);

  /** Returns the meta data for the node */
  public MetaData getMetaData();

  /** Returns the names and meta data for the children of a directory */
  public Map<String, MetaData> readDir();

  /** Deletes the node if it has no children */
  public void delete();
  
  /**
   * Locking modes
   */
  /** Multiple readers */
  public final static int LOCK_SHARED = 1;
  /** Single writer */
  public final static int LOCK_EXCLUSIVE = 2;
  
  /**
   * Acquire a lock. Block if the lock cannot be obtained immediately.
   * @param lockMode one of the lock modes above
   */
  public void lock(int lockMode);
  
  /**
   * Attempt to acquire a lock. Do not block if the lock cannot be obtained immediately.
   * @param lockMode - one of the lock modes above
   * @return - true if lock was acquired, false if lock was not acquired.
   */
  public boolean tryLock(int lockMode);
  
  /** Releases the currently held lock */
  public void unlock();

  /** Returns a byte array that describes any lock held by this handle */
  public byte[] getSequencer();
  
  /**
   * Associates a new sequencer with this session
   * @param sequencer - A sequencer returned from some other session, possibly on
   *                    another server.
   */
  public void setSequencer(byte[] sequencer);
  
  /**
   * Returns true if the specified sequencer is valid.
   * @param sequencer
   * @return true if sequencer is valid, false if not.
   */
  public boolean checkSequencer(byte[] sequencer);
}
}}}

=== Event Handler API ===

{{{
package org.apache.hbase.lockserver.client;

/**
 * Clients register for events with the {@see LockserverClient}
 * 
 * This interface defines the API for all the events, but clients need not
 * register for all the event types. In this case, only a stub method is
 * required to implement this interface.
 *
 */
public interface LockEventHandler {
  /** Called when contents of node are modified */
  public void contentsModified();
  /** Called when a new child node is added */
  public void childAdded();
  /** Called when a child node is removed */
  public void childRemoved();
  /** Called when a child node is modified */
  public void childModified();
  /** Called when the master lock server fails over */
  public void masterFailover();
  /** Called when the session is in jeopardy of timing out */
  public void handleWarning();
  /**
   * Called if the session was in jeopardy but was able to communicate with
   * the lock server before the session timed out.
   */
  public void handleSafe();
  /**
   * Called if the session was in jeopardy and was not able to communicate with
   * the lock server before the session timed out.
   */
  public void handleExpired();
}
}}}

=== Lock Meta Data ===

{{{
package org.apache.hbase.lockserver.client;

/** Information about a node in the lock server hierarchy */
public interface MetaData {
  /** Returns the ACL that controls read access */
  public String getReadACL();
  /** Returns the ACL that controls write access */
  public String getWriteACL();
  /** Returns the ACL that controls ACL changes */
  public String getControlACL();
  /** Returns the instance number of the node */
  public long getInstance();
  /** Returns the content generation number (files only) */
  public long getContentGeneration();
  /** Returns the lock generation number */
  public long getLockGeneration();
  /** Returns the ACL generation number */
  public long getACLGeneration();
  /** Returns the content checksum */
  public long getContentChecksum();
}
}}}

Mime
View raw message