Re: The New Device API (tm)

"Ingo Weinhold" <bonefish-CFLBMwTPW48UNGrzBIF7/[email protected]> wrote:
> as promised I worked out a draft for a new Device API. Let me list 
> general requirements first:

Nice!
In fact, I would have let you decide if you wanted to do this - my 
opinion about the Device API is: either recreating it 100% compatible, 
or making a complete and nice replacement.
But of course, I prefer the latter - I like to have clean APIs :)

> user API:
> 
> * convenient traversal of devices, sessions and partitions
> * advanced iteration (as provided by the old API)
> * FS initialization, partitioning, low-level formatting
> * ejection of removable media
> * notifications on changes, including the following events:
>   - mount point changes (renaming, moving)
>   - mounting/unmounting
>   - FS initialization, partitioning and low-level formatting
>   - media changes
>   - appearance/disappearance of devices

I am not sure if I like that - but the only reason for this is the 
relatively big amount of overlaps it has with BVolume & BVolumeRoster -
 I think it's better to have a clear differentiation between both 
classes.

> Like the old API the new one shall only deal with disk devices (`/dev
> /
> disk/...'); mounted file images are ignored.

Well, if mounting/unmounting notifications are part of the class, then 
they are not completely ignored (nitpicking me) :)

> ...
> As already mentioned in earlier mails, in my opinion the R2+ features 
> are rather orthogonal to what we plan for R1, and therefore there's 
> not 
> much to take care of to not create something that can't be extended 
> with the listed features.

Yes, you are probably right. We'll see that later ;)

> The disk=5Fscanner as implemented seems to basically meet the 
> requirements. The notification support still needs to be added, of 
> course. Unless I'm mistaken, some notifications needed for the user 
> API 
> are not yet sended by the kernel, namely for low-level formatting, 

Where do you think those notifications are necessary/helpful=3F
BTW for hot-pluggable devices, the whole disk could go away at any 
point in time.

> media changes and appearance/disappearance of devices. Unless there 
> are 
> reasons why this shouldn't be done, I would like to see them added to 
> the OBOS kernel. For development and test under BeOS R5, at least the 
> latter ones can be worked around by polling.

Not only for R5 - the kernel have to poll for media changes as well, 
but of course, that's the right solution. The kernel should take care 
of that, and sending out notifications is a good thing.

> As already outlined in an earlier mail, I think, the best way do deal 
> with the different change events is to bundle all the basic activity 
> in 
> one entity. In principle that entity could live in the user 
> application, but since it will need to run at least one extra thread 
> (a 
> BLooper; maybe another one for polling), it is probably better to 
> place 
> it in a server, namely the registrar. The additional communication 
> overhead should be acceptable, even if each method call would require 
> a 
> message exchange with the registrar (similar to the BMimeType 
> implementation). If iteration turned out to be slow, optimizations 
> were 
> possible.

Dunno, we could also just copy the current node monitor behaviour - the 
kernel would then send out the notification directly to the correct 
receiver.
It would be pretty easy to "abuse" that mechanism for these things - in 
fact, it's already planned to do so for mount/unmount events.

> Before continuing, I should introduce the classes I envision for the 
> API:
> * BDiskDeviceRoster: The roster that knows about disk devices. It can 
> be used to iterate through the devices and to register/unregister for 
> notifications

I don't get the ID part - what exactly is that, and how can it be 
persistent=3F
And I would like "ForEach" instead of "Each" better, but I am not a 
native speaker.
Also, a "what" field for the message is not defined yet.

> * BDiskDevice: Replaces Device. Will provide similar functionality.

I would suggest the following name changes (again, I am not a native 
speaker, I would just prefer them for whatever reason, feel free to 
ignore me :-))
- NoMedia() to HasMedia() or similar
- Format() to LowLevelFormat() (would at least save a comment ;)
- Name() to Path() or DevicePath()
- GetDisplayName() to GetName() or something similar, maybe also have a 
"char *" version of it to follow the (in this regard) broken Be API=3F
- again "ForEach...()"

What exactly does Traverse() do=3F Iterate over all sessions/partitions=3F
Should the Session class functionality be mixed with the BDiskDevice=3F 
(CountPartitions(), EachPartition()=3F) I am not sure about this, but if 
it would be really convenient...
What exactly is IsFloppy() for=3F
What exactly does Synchronize() and why is it necessary=3F

> * BSession: Replaces Session. Will provice similar functionality 
> (partitioning will be new).

Index() is the index in the list of sessions for this device=3F
IsVirtual() means there is no on-disk session structure, i.e. for hard 
disks=3F

> * BPartition: Replaces Partition. Will provide similar functionality.

What does IsEmpty() mean here=3F
Should Type() be a string=3F Wouldn't it be better if we had IDs, like 
B=5FINTEL=5FPARTITION =3D 'intl'=3F But I might be wrong here :-)
Perhaps rename VolumeID() to Device()=3F
For mount(): I want to have real parameter strings, so that you could 
replace "void *params" with "const char *params" as it is done in 
Initialize().
I would also rename GetMountPointNodeRef() to GetMountPoint() and add 
versions of it to return a BEntry and a entry=5Fref.
I would also like to get rid of the IsBFS(), IsHFS(), IsOFS() methods -
 those are strange convenience functions to me.
(and I want to have a FindDirectory()-like call in the FS API as well)

FileSystemFlags() is difficult - at least a file system would need to 
return a value without having a mounted file system - at least for 
B=5FREAD=5FONLY this not possible; all other things should be simple 
(although not every BFS disk has to have indices).

PublishDevice() should not be necessary - at least I would like to get 
rid of it, and let the kernel automatically create them as needed. 
Ideas welcome, I haven't thought much about it, I just don't like the 
way it's currently done :-)

> Regarding the naming: I find BDevice simply too general. BDisk would 
> be 
> fine in principle, but there may be potential for mixing it up with 
> BVolume. BStorageDevice would be most accurate, but also a bit 
> longer. 
> :-P

BDiskDevice is fine, I would like BStorageDevice better - although 
BDiskDevice better covers the topic, I think (dunno why, though).

Anyway, have to go now, perhaps I'll add something later:
[.......]

Adios...
   Axel.