ceph/ceph — pull request #937 by christian-marie (2013-12-13 02:26:53+00:00)
Title: Document librados's rados_write's behaviour in reguards to return value.

Hi, as per a conversation in #ceph-devel I would like to add a note documenting this rather inconsistent and misleading behaviour:

12:34 < pingu> I'm writing some bindings for haskell to librados.
12:34 < pingu> can anyone tell me why rados_write would return a byte count
less than that of the buffer provided to it?
12:35 < pingu> as rados_write_full doesn't seem to do any such thing.
12:38 < joshd> it would never return less than the full length, only errors
like EPERM, ENOSPC, etc.
12:38 < joshd> rados_read may return a smaller number of bytes read if it
would be past the end of the object
12:39 < pingu> joshd: okay, thanks. So that's rados_write that will never
return less than the full length?
12:39 < joshd> yeah
12:39 < pingu> That seems a bit misguiding to return a size that you never
need to look at does it not?
12:40 < pingu> Surely if you don't need to care about the return value, it
should just return zero on success?
12:40 < pingu> I am looking at:
http://ceph.com/docs/master/rados/api/librados/#rados_write
12:40 < joshd> yes, unfortunately we're stuck with it for backwards
compatibliity
12:41 < pingu> Okay. Thanks. Maybe the documentation could note that?
12:41 < joshd> it certainly could (it's generated from the header)
12:42 -!- zhyan_ [~zhyan@134.134.137.73] has joined #ceph-devel
12:45 -!- yanzheng [~zhyan@jfdmzpr04-ext.jf.intel.com] has quit [Remote host
closed the connection]
12:54 <@dmick> that's the "standard" for *write interfaces, really: return the
length written.
12:54 <@dmick> it just so happens this one won't return less, but all the rest
have the same convention
12:55 < pingu> I certainly wouldn't expect any library to follow a "standard"
interface though.
12:56 < pingu> That would be rather overly hopeful.
12:56 < pingu> And as such, I think it'd be a good idea to document that it's
returning a value you can feel free to ignore.
12:56 < pingu> I wouldn't be surprised if someone out there has implemented a
retry-if-less-is-written loop.
12:58 -!- rturk-away is now known as rturk
12:59 -!- rturk is now known as rturk-away
13:01 <@dmick> right, but that loop is fine
13:01 <@dmick> and the point was that it's a convention amongst many libraries
(like, libc)
13:01 -!- xarses [~andreww@64-79-127-122.static.wiline.com] has quit [Ping
timeout: 480 seconds]
13:02 < pingu> it's fine, sure, but it's wasting peoples time implementing
code that will never be used.
13:02 <@dmick> sigh. yes, it is. yes, it should be documented. drive on.