#

# CDDL HEADER START

#

# The contents of this file are subject to the terms of the

# Common Development and Distribution License (the "License").

# You may not use this file except in compliance with the License.

#

# You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE

# or http://www.opensolaris.org/os/licensing.

# See the License for the specific language governing permissions

# and limitations under the License.

#

# When distributing Covered Code, include this CDDL HEADER in each

# file and include the License file at usr/src/OPENSOLARIS.LICENSE.

# If applicable, add the following below this CDDL HEADER, with the

# fields enclosed by brackets "[]" replaced with your own identifying

# information: Portions Copyright [yyyy] [name of copyright owner]

#

# CDDL HEADER END

#

# Copyright 2009 Sun Microsystems, Inc.  All rights reserved.

# Use is subject to license terms.

"""object to map content hashes to file paths

The Layout class hierarchy encapsulates bijective mappings between a hash

(or file name since those are equivalent in our system) and a relative path

that describes where to place that file in the file system.  This bijective

relation should hold when the union of all layouts is considered as a single

set of mappings.  In practical terms, this means that only one layout may

potentially deposit a hash into any particular location.  This is not a

difficult requirement to satisfy since each layout may append a unique

identifier to the file name or choose to carve out its own namespace at some

level of directory hierarchy.

The V1Layout places each file into a single layer of 256 directories.  A

fanout of 256 provides good performance compared to the other layouts

tested.  It also allows over 8M files to be stored even with filesystems

which limit the number of files in a directory to 65k.

The V0Layout layout uses two layers of directories; the first has a fanout

of 256 while the second has a fanout of 16M.  This layout has the problem

that for the sizes of images (on the order of 300-500k files) and repos (on

the order of 1M files), the second director level usually contains a single

file.  This imposes a substantial penalty for removing or resyncing the

directories because a readdir(3C) must be done for each directory and

readdir is two orders of magnitude slower than the open or read ZFS

operations, and one order of magnitude slower than ZFS remove.  Reducing

the number of directories used to hold the downloaded files was a goal for

the next layout.

To evaluate a layout, it is necessary to measure the insertion time, the

removal time, and the time to open a random file.  The insertion time

affects the publication speed.  The removal time effects the time a client

may take to clear its download cache.  The access time effects how quickly

a server can open a file to serve it.  File sizes from 1 to 10M were used

to asses the scalability of the different layouts."""

import os

class Layout(object):

        """This class is the parent class to all layouts. It defines the

        interface which those subclasses must satisfy."""

        def lookup(self, hashval):

                """Return the path to the file with name "hashval"."""

                raise NotImplementedError

        def path_to_hash(self, path):

                """Return the hash which would map to "path"."""

                raise NotImplementedError

        def contains(self, rel_path, file_name):

                """Returns whether this layout would place a file named

                "file_name" at "rel_path"."""

                return self.lookup(file_name) == rel_path

class V0Layout(Layout):

        """This class implements the original layout used.  It uses a 256 way

        split (2 hex digits) followed by a 16.7M way split (6 hex digits)."""

        def lookup(self, hashval):

                """Return the path to the file with name "hashval"."""

                return os.path.join(hashval[0:2], hashval[2:8], hashval)

        def path_to_hash(self, path):

                """Return the hash which would map to "path"."""

                return os.path.basename(path)

class V1Layout(Layout):

        """This class implements the new layout approach which is a single 256

        way fanout using the first two digits of the hash."""

        def lookup(self, hashval):

                """Return the path to the file with name "hashval"."""

                return os.path.join(hashval[0:2], hashval)

        def path_to_hash(self, path):

                """Return the hash which would map to "path"."""

                return os.path.basename(path)

def get_default_layouts():

        """This function describes the default order in which to use the

        layouts defined above."""

        return [V1Layout(), V0Layout()]

def get_preferred_layout():

        """This function returns the single preferred layout to use."""

        return V1Layout()