API robustness - (was: Different ways to create a directory)

[David Faure]

On Friday 14 August 2009, Rafael Fernández López wrote:
> >  in the Qt one. So the fix is not KDE5, but adding mode_t to QDir::mkpath()
> >  so that we can get rid of KStandardDirs::makeDir.
> 
> Yes, that is what I meant. KStandardDirs::makeDir can be removed.

... only once you make a Qt merge request that adds mode_t support to QDir::mkpath()
(but this can be done today, no need to wait for KDE 5 for that bit. Then we can
deprecated KStandardDirs::makeDir and port the code to mkpath, without waiting
for kde 5 either.)

> > OK the one thing I see for kde 5 is removing NetAccess since job->exec()
> >  does the same (with the same dangers), but that's not what you had in mind
> >  :)
> 
> I did not have this in mind since I consider having a synchronous API is also 
> a good idea for certain goals. Obviously NetAccess could be removed, since it 
> is only making what KIO does in a synchronous way, but we would make it harder 
> for developers working synchronously with this API. But I am not in favour of 
> removing NetAccess, for this reason I did not even proposed this option.

There is nothing hard about calling exec().
I think you're missing the point that I wanted to make: I agree, a sync api is
sometimes useful (in apps that are not complex enough to break on nested
event loops...). I'm just saying that instead of the one-line NetAccess::mkdir
you can use the two-line KIO::mkdir + job->exec(). That's a great step forward
in removing the number of available APIs for doing a given operation, you should
be all in favour of it, I would think :)

> As you wish guys, but I some time ago (months?) still have seen comments 
> //TODO KDE2. ;)
Can't remember seeing that. But we did go through a lot of "TODO KDE4"
for kde4, even if not all of them.

> As a develoer, I'd prefer to see some kind of "intelligence" in the API that 
> saves me work, for instance:
> 
> KFoo::makeDir("ftp://foo:bar@host/myDir");

1) nested event loop = dangerous.
2) possibly very slow if this FTP site is very slow to answer

> KFoo::makeDir("file:///home/user/myDir");

1) direct calls (if implemented with QDir) = safe.
2) should be fast

=> definitely not the same.

> Behind the scenes, it should be done automatically what's needed in order to 
> create that directory, but from an API user perspective this is the best 
> thing, since the API is consistent, and is robust, because it does not matter 
> where the directory is going to be created, the API user _knows_ wherever the 
> directory is going to be created, he can always trust in KFoo::makeDir, 
> because behind the scenes it will take the right decisions in order for the 
> directory be created.

I'll have to repeat myself again:
1) Nested event loops are dangerous (and there is no way to implement
  makeDir(ftp://) without an event loop currently)
2) Synchronous network operations are very bad, they block the GUI for
an indefinite amount of time.

We have worked hard enough the last 10 years in order to provide a safe and
asynchronous API for network operations, I don't want to see kde switching
to blocking calls like KFoo::makeDir("ftp://foo:bar@host/myDir") and random
apps hanging at random times because some server is slow to answer.
That would be disaster.

Ideally all network operations should be done asynchronously.
But surely you don't want to make async calls for creating a local directory
or file, that would bloat up all the code that works with local caches and config
files and stuff!

-- 
David Faure, faure at kde.org, sponsored by Qt Software @ Nokia to work on KDE,
Konqueror (http://www.konqueror.org), and KOffice (http://www.koffice.org).