NAME

MogileFS::Client - Client library for the MogileFS distributed file system.

SYNOPSIS

 use MogileFS::Client;

 # create client object w/ server-configured namespace and IPs of trackers
 $mogc = MogileFS::Client->new(domain => "foo.com::my_namespace",
                               hosts  => ['10.0.0.2', '10.0.0.3']);

 # create a file
 $key   = "image_of_userid:$userid";   # mogile is a flat namespace.  no paths.
 $class = "user_images";               # must be configured on server
 $fh = $mogc->new_file($key, $class);

 print $fh $data;

 unless ($fh->close) {
    die "Error writing file: " . $mogc->errcode . ": " . $mogc->errstr;
 }

 # Find the URLs that the file was replicated to.  May change over time.
 @urls = $mogc->get_paths($key);

 # no longer want it?
 $mogc->delete($key);

DESCRIPTION

This module is a client library for the MogileFS distributed file system. The class method 'new' creates a client object against a particular mogilefs tracker and domain. This object may then be used to store and retrieve content easily from MogileFS.

METHODS

new

  $client = MogileFS::Client->new( %OPTIONS );

Creates a new MogileFS::Client object.

Returns MogileFS::Client object on success, or dies on failure.

OPTIONS:

hosts

Arrayref of 'host:port' strings to connect to as backend trackers in this client.

domain

String representing the mogile domain which this MogileFS client is associated with. (All create/delete/fetch operations will be performed against this mogile domain). See the mogadm shell command and its 'domain' category of operations for information on manipulating the list of possible domains on a MogileFS system.

reload

  $mogc->reload( %OPTIONS )

Re-init the object, like you'd just reconstructed it with 'new', but change it in-place instead. Useful if you have a system which reloads a config file, and you want to update a singleton $mogc handle's config value.

last_tracker

Returns a scalar of form "ip:port", representing the last mogilefsd 'tracker' server which was talked to.

errstr

Returns string representation of the last error that occured. It includes the error code (same as method 'errcode') and a space before the optional English error message.

This isn't necessarily guaranteed to reset after a successful operation. Only call it after another operation returns an error.

errcode

Returns an error code. Not a number, but a string identifier (e.g. "no_domain") which is stable for use in error handling logic.

This isn't necessarily guaranteed to reset after a successful operation. Only call it after another operation returns an error.

readonly

  $is_readonly = $mogc->readonly
  $mogc->readonly(1)

Getter/setter to mark this client object as read-only. Purely a local operation/restriction, doesn't do a network operation to the mogilefsd server.

new_file

  $mogc->new_file($key)
  $mogc->new_file($key, $class)
  $mogc->new_file($key, $class, $opts_hashref)

Start creating a new filehandle with the given key, and option given class and options.

Returns a filehandle you should then print to, and later close to complete the operation. NOTE: check the return value from close! If your close didn't succeed, the file didn't get saved!

$opts_hashref can contain keys:

fid

Explicitly specify the fid number to use, rather than it being automatically allocated.

create_open_args

Hashref of extra key/value pairs to send to mogilefsd in create_open phase.

create_close_args

Hashref of extra key/value pairs to send to mogilefsd in create_close phase.

store_file

  $mogc->store_file($key, $class, $fh_or_filename[, $opts_hash])

Wrapper around new_file, print, and close.

Given a key, class, and a filehandle or filename, stores the file contents in MogileFS. Returns the number of bytes stored on success, undef on failure.

store_content

    $mogc->store_content($key, $class, $content[, $opts]);

Wrapper around new_file, print, and close. Given a key, class, and file contents (scalar or scalarref), stores the file contents in MogileFS. Returns the number of bytes stored on success, undef on failure.

get_paths

  @paths = $mogc->get_paths($key)
  @paths = $mogc->get_paths($key, $no_verify_bool); # old way
  @paths = $mogc->get_paths($key, { noverify => $bool }); # new way

Given a key, returns an array of all the locations (HTTP URLs) that the file has been replicated to.

If the "no verify" option is set, the mogilefsd tracker doesn't verify that the first item returned in the list is up/alive. Skipping that check is faster, so use "noverify" if your application can do it faster/smarter. For instance, when giving Perlbal a list of URLs to reproxy to, Perlbal can intelligently find one that's alive, so use noverify and get out of mod_perl or whatever as soon as possible.

get_file_data

  $dataref = $mogc->get_file_data($key)

Wrapper around get_paths & LWP, which returns scalarref of file contents in a scalarref.

Don't use for large data, as it all comes back to you in one string.

delete

    $mogc->delete($key);

Delete a key from MogileFS.

rename

  $mogc->rename($oldkey, $newkey);

Rename file (key) in MogileFS from oldkey to newkey. Returns true on success, failure otherwise.

list_keys

    @keys = $mogc->list_keys($prefix, $after[, $limit]);

Used to get a list of keys matching a certain prefix.

$prefix specifies what you want to get a list of. $after is the item specified as a return value from this function last time you called it. $limit is optional and defaults to 1000 keys returned.

In list context, returns ($after, $keys). In scalar context, returns arrayref of keys. The value $after is to be used as $after when you call this function again.

When there are no more keys in the list, you will get back undef or an empty list.

foreach_key

  $mogc->foreach_key( %OPTIONS, sub { my $key = shift; ... } );
  $mogc->foreach_key( prefix => "foo:", sub { my $key = shift; ... } );

Functional interface/wrapper around list_keys.

Given some %OPTIONS (currently only one, "prefix"), calls your callback for each key matching the provided prefix.

set_pref_ip

  $mogc->set_pref_ip({ "10.0.0.2" => "10.2.0.2" });

Weird option for old, weird network architecture. Sets a mapping table of preferred alternate IPs, if reachable. For instance, if trying to connect to 10.0.0.2 in the above example, the module would instead try to connect to 10.2.0.2 quickly first, then then fall back to 10.0.0.2 if 10.2.0.2 wasn't reachable.

PLUGIN METHODS

WRITEME

HOOKS

add_hook

WRITEME

add_backend_hook

WRITEME

SEE ALSO

http://www.danga.com/mogilefs/

COPYRIGHT

This module is Copyright 2003-2004 Brad Fitzpatrick, and copyright 2005-2007 Six Apart, Ltd.

All rights reserved.

You may distribute under the terms of either the GNU General Public License or the Artistic License, as specified in the Perl README file.

WARRANTY

This is free software. IT COMES WITHOUT WARRANTY OF ANY KIND.

AUTHORS

Brad Fitzpatrick <brad@danga.com>

Brad Whitaker <whitaker@danga.com>

Mark Smith <marksmith@danga.com>