FreeLists / openbeosstorage / [openbeosstorage] Re: Compatibility Policy

[Tyler Dauwalder <tyler@xxxxxxxxxxxxx>]

> > > * R5 inconsistencies:
> > >   Shall inconsistencies of R5 be reproduced? I don't have the code at
> > >   hand, so I can't give an example, but I remember, that I had two
> > >   versions of a method, that returned different results for the same
> > >   input. Boolean methods, btw...
> > 
> > If one's returning true and the other false on the same input, that could
> > be bad. I'd consider something like that to be similar to a bug, and 
> > handle
> > it as such. Am I interpreting you correctly?
> 
> To give the example I referred to:
> BDirectory::Contains(): If the directory is uninitialized, the const char*
> version taking a path, returns true, if the entry exists, whereas the
> BEntry* version always returns false.
> Being a lazy programmer I of course implemented one version using the
> other, so that now both versions return true in this case.
> I vaguely remember that there where other methods, of which different
> versions returned different error codes for the same error.

That's kind of a tough one. I think those functions should have returned a 
status_t: B_OK if it exists, B_ENTRY_NOT_FOUND if it doesn't, and B_NO_INIT 
if unitialized. 

Doing what the R5 version does is safe. That's probably more important for us 
currently than having them standardized (though it *is* important for that 
behavior to be described in our doxygen documentation, as it is).

Then, for post-R1 I think we should replace (or augment) them with versions 
that return status_t's. What do you think?

> > 1. Error codes with a functional meaning. An example of this would be
> > BEntry::GetParent() returning B_ENTRY_NOT_FOUND when the entry is "/".
> > B_ENTRY_NOT_FOUND *needs* to be returned in this instance. Further, any
> > other error *needs* to return something *other* than B_ENTRY_NOT_FOUND.
> >
> > 2. Error codes with no significant functional meaning. These are the bulk
> > of errors returned, and most people will likely just check for (result <
> > B_OK). Sure they have specific meaning (B_NO_MEMORY, B_BAD_VALUE, etc.),
> > but they'll generally be handled identically.
> > 
> > 3. B_OK (or otherwise meaningful positive values)
> > 
> > Error codes of types 1 and 3 are to have no inconsistencies. Error codes 
> > of
> > type 2 pretty much just have to be an error code (i.e. < B_OK). They can
> > always be B_DEV_DOOR_OPEN for all anyone cares.
>
> Do I understand you correctly, that you are saying, that if R5 violates
> the rule for 1, OBOS has to do it differently (i.e. correctly)?

No. Error codes that are functionally significant should match the R5 result. 
BEntry::GetParent() *needs* to return B_ENTRY_NOT_FOUND if the entry is the 
root directory.

> And that in the case of 2, we don't have to care, what R5 returns, but
> return any value of the set that we think fits best?

Basically yes (though it's obviously better to return something that makes 
sense than returning B_BAD_MIME_SNIFFER_RULE all the time).

> I guess 3 is a special case anyway, since returning or not returning B_OK
> is the border between success and failure, which rather belongs to the bug
> section.

Yes. B_OK should only be returned on success. Otherwise something's broken.

> > Personally, I would also prefer these inconsistencies to be standardized  
> > but I don't know that we're the ones (at the moment) to be making the
> > standards.
> > The difficult thing from our point of view is that many of our return
> > values are just handed back from kernel_interface calls. So the real
> > standardization needs to occur in the kernel.
> Even beyond, I guess most of the return values originate from the file
> systems.

Good point.

> Yep you're absolutely right.
> What I was thinking of are the error values we produce ourselves.
> And to standardize those, some questions need to be answered, such as:
> 
> * What value to return, if on an uninitialized object a method is invoked 
>   that requires the object to be properly initialized? The InitCheck()
>   return value, B_NO_INIT or B_FILE_ERROR?

You're right, it would be nice for this to be standardized (B_FILE_ERROR 
should not be returned, IMO, but IIRC R5 does this in a number of cases), but 
there are also times where something other than B_NO_INIT should be returned 
(e.g. after trying to create a BNode on a locked file, InitCheck() should 
return B_BUSY).

> * In which order shall possible errors be checked? First arguments, then
>   InitCheck() or the other way around?

Pick one and let me know :-). I can't say that really it matters to me, but 
I'm all for being consistent.

> * If a method invoked on an object, is supposed to initialize another
>   object that is passed as an argument, what happens to the object, if the
>   method fails? Unset() it at the end of the method, if an error occured
>   or always Unset() it at the beginning of the method and leave it in the
>   state it happens to be at the end of the method.

I like Unset()ing it at the beginning because it's easy to implement (so it's 
easy to be consistent). Can you think of an example where this wouldn't be a 
good idea (I can't at the moment...I need to go to bed though ;-).

> PS: I don't know, if I already mentioned it, BEntry doesn't handle too
>     long entry names and cyclic links correctly. Please tell me, when you
>     have fixed this. Then I can uncomment some of the BDirectory test
>     cases.

Yes I know, you've mentioned it :-). I'm sorry, I really haven't had time to 
do *anything* this quarter. I'm lucky to be staying on top of my admin 
duties. Due to my lack of availability, you are hereby completely welcome to 
fix anything of mine that has frustrated you to the point of being motivated 
enough to fix it yourself. Otherwise, I shall get to it as soon as I can 
(I'll even put off polishing up my doxygen stuff, which I'm finally getting 
the hang of :-).

-Tyler