1MogileFS::Client(3) User Contributed Perl Documentation MogileFS::Client(3)
2
6 MogileFS::Client - Client library for the MogileFS distributed file
7 system.
8
10 use MogileFS::Client;
11 # create client object w/ server-configured namespace
13 # and IPs of trackers
14 $mogc = MogileFS::Client->new(domain => "foo.com::my_namespace",
15 hosts => ['10.0.0.2', '10.0.0.3']);
16 # create a file
18 # mogile is a flat namespace. no paths.
19 $key = "image_of_userid:$userid";
20 # must be configured on server
21 $class = "user_images";
22 $fh = $mogc->new_file($key, $class);
23 print $fh $data;
25 unless ($fh->close) {
27 die "Error writing file: " . $mogc->errcode . ": " . $mogc->errstr;
28 }
29 # Find the URLs that the file was replicated to.
31 # May change over time.
32 @urls = $mogc->get_paths($key);
33 # no longer want it?
35 $mogc->delete($key);
36
38 This module is a client library for the MogileFS distributed file sys‐
39 tem. The class method 'new' creates a client object against a particu‐
40 lar mogilefs tracker and domain. This object may then be used to store
41 and retrieve content easily from MogileFS.
42
44 new
45 $client = MogileFS::Client->new( %OPTIONS );
47 Creates a new MogileFS::Client object.
49 Returns MogileFS::Client object on success, or dies on failure.
51 OPTIONS:
53 hosts
55 Arrayref of 'host:port' strings to connect to as backend trackers
56 in this client.
57 domain
59 String representing the mogile domain which this MogileFS client is
60 associated with. (All create/delete/fetch operations will be per‐
61 formed against this mogile domain). See the mogadm shell command
62 and its 'domain' category of operations for information on manipu‐
63 lating the list of possible domains on a MogileFS system.
64 reload
66 $mogc->reload( %OPTIONS )
68 Re-init the object, like you'd just reconstructed it with 'new', but
70 change it in-place instead. Useful if you have a system which reloads
71 a config file, and you want to update a singleton $mogc handle's config
72 value.
73 last_tracker
75 Returns a scalar of form "ip:port", representing the last mogilefsd
77 'tracker' server which was talked to.
78 errstr
80 Returns string representation of the last error that occured. It
82 includes the error code (same as method 'errcode') and a space before
83 the optional English error message.
84 This isn't necessarily guaranteed to reset after a successful opera‐
86 tion. Only call it after another operation returns an error.
87 errcode
89 Returns an error code. Not a number, but a string identifier (e.g.
91 "no_domain") which is stable for use in error handling logic.
92 This isn't necessarily guaranteed to reset after a successful opera‐
94 tion. Only call it after another operation returns an error.
95 readonly
97 $is_readonly = $mogc->readonly
99 $mogc->readonly(1)
100 Getter/setter to mark this client object as read-only. Purely a local
102 operation/restriction, doesn't do a network operation to the mogilefsd
103 server.
104 new_file
106 $mogc->new_file($key)
108 $mogc->new_file($key, $class)
109 $mogc->new_file($key, $class, $opts_hashref)
110 Start creating a new filehandle with the given key, and option given
112 class and options.
113 Returns a filehandle you should then print to, and later close to com‐
115 plete the operation. NOTE: check the return value from close! If your
116 close didn't succeed, the file didn't get saved!
117 $opts_hashref can contain keys:
119 fid Explicitly specify the fid number to use, rather than it being
121 automatically allocated.
122 create_open_args
124 Hashref of extra key/value pairs to send to mogilefsd in cre‐
125 ate_open phase.
126 create_close_args
128 Hashref of extra key/value pairs to send to mogilefsd in cre‐
129 ate_close phase.
130 store_file
132 $mogc->store_file($key, $class, $fh_or_filename[, $opts_hash])
134 Wrapper around new_file, print, and close.
136 Given a key, class, and a filehandle or filename, stores the file con‐
138 tents in MogileFS. Returns the number of bytes stored on success,
139 undef on failure.
140 store_content
142 $mogc->store_content($key, $class, $content[, $opts]);
144 Wrapper around new_file, print, and close. Given a key, class, and
146 file contents (scalar or scalarref), stores the file contents in
147 MogileFS. Returns the number of bytes stored on success, undef on fail‐
148 ure.
149 get_paths
151 @paths = $mogc->get_paths($key)
153 @paths = $mogc->get_paths($key, $no_verify_bool); # old way
154 @paths = $mogc->get_paths($key, { noverify => $bool }); # new way
155 Given a key, returns an array of all the locations (HTTP URLs) that the
157 file has been replicated to.
158 noverify
160 If the "no verify" option is set, the mogilefsd tracker doesn't
161 verify that the first item returned in the list is up/alive. Skip‐
162 ping that check is faster, so use "noverify" if your application
163 can do it faster/smarter. For instance, when giving Perlbal a list
164 of URLs to reproxy to, Perlbal can intelligently find one that's
165 alive, so use noverify and get out of mod_perl or whatever as soon
166 as possible.
167 zone
169 If the zone option is set to 'alt', the mogilefsd tracker will use
170 the alternative IP for each host if available, while constructing
171 the paths.
172 pathcount
174 If the pathcount option is set to a positive integer greater than
175 2, the mogilefsd tracker will attempt to return that many different
176 paths (if available) to the same file. If not present or out of
177 range, this value defaults to 2.
178 get_file_data
180 $dataref = $mogc->get_file_data($key)
182 Wrapper around get_paths & LWP, which returns scalarref of file con‐
184 tents in a scalarref.
185 Don't use for large data, as it all comes back to you in one string.
187 delete
189 $mogc->delete($key);
191 Delete a key from MogileFS.
193 rename
195 $mogc->rename($oldkey, $newkey);
197 Rename file (key) in MogileFS from oldkey to newkey. Returns true on
199 success, failure otherwise.
200 list_keys
202 @keys = $mogc->list_keys($prefix, $after[, $limit]);
204 Used to get a list of keys matching a certain prefix.
206 $prefix specifies what you want to get a list of. $after is the item
208 specified as a return value from this function last time you called it.
209 $limit is optional and defaults to 1000 keys returned.
210 In list context, returns ($after, $keys). In scalar context, returns
212 arrayref of keys. The value $after is to be used as $after when you
213 call this function again.
214 When there are no more keys in the list, you will get back undef or an
216 empty list.
217 foreach_key
219 $mogc->foreach_key( %OPTIONS, sub { my $key = shift; ... } );
221 $mogc->foreach_key( prefix => "foo:", sub { my $key = shift; ... } );
222 Functional interface/wrapper around list_keys.
224 Given some %OPTIONS (currently only one, "prefix"), calls your callback
226 for each key matching the provided prefix.
227 set_pref_ip
229 $mogc->set_pref_ip({ "10.0.0.2" => "10.2.0.2" });
231 Weird option for old, weird network architecture. Sets a mapping table
233 of preferred alternate IPs, if reachable. For instance, if trying to
234 connect to 10.0.0.2 in the above example, the module would instead try
235 to connect to 10.2.0.2 quickly first, then then fall back to 10.0.0.2
236 if 10.2.0.2 wasn't reachable.
237
239 WRITEME
240
242 add_hook
243 WRITEME
245 add_backend_hook
247 WRITEME
249
251 <http://www.danga.com/mogilefs/>
252
254 This module is Copyright 2003-2004 Brad Fitzpatrick, and copyright
255 2005-2007 Six Apart, Ltd.
256 All rights reserved.
258 You may distribute under the terms of either the GNU General Public
260 License or the Artistic License, as specified in the Perl README file.
261
263 This is free software. IT COMES WITHOUT WARRANTY OF ANY KIND.
264
266 Brad Fitzpatrick <brad@danga.com>
267 Brad Whitaker <whitaker@danga.com>
269 Mark Smith <marksmith@danga.com>
271perl v5.8.8 2007-08-06 MogileFS::Client(3)