[Development] Calendar classes: API review request

[Simon Hausmann]

On Dienstag, 31. Juli 2018 14:25:21 CEST Edward Welbourne wrote:
> > My primary concern with this API is that it promotes an unclear
> > ownership model.
> 
> hmm ... this is partly a symptom of most QAbstractCalendar instances
> being dataless.  Each calendar has different code to implement its
> behaviour.  Or, to put it another way, the vtable is the data.
> 
> Admittedly, I can imagine uses for derived classes that do have data
> (e.g. for historians of Europe, taking into account the use of Julian
> for part of history, Gregorian for other parts, with diverse dates for
> the transition - and some foibles in between), so we should make it
> possible for them to have data.
> 
> > Typically we have API that is either a sub-class of QObject (where the
> > parent may delete the children, such as QFile) or we have value based
> > classes (such as QDateTime). There is also a slightly less common,
> > third model with explicitly shared types, I think mostly acting as
> > singletons.
> 
> All of which is mostly about how *the data* is shared.
> 
> > With QAbstractCalendar there's an entirely new model (which also
> > includes a clone() method). I think that model should [be]
> > reconsidered,
> 
> Can you suggest an alternative ?

If you are sure that there is no data to be dealt with, that the calendars are 
free of state, then they should probably become singletons.

You can still have a factory on the backend, but for the users of API there 
would be only pointers to calendar objects that are supposed to remain valid 
for the life time of the program.
 
> > but if not, then it needs to be documented and it needs to be
> > clarified how this model applies to the exposure of calendars to
> > QML. Otherwise you easily risk creating dangling pointers (as pointed
> > out in the QML review).
> > 
> > A secondary concern is that the API, once submitted, is not
> > extensible. We cannot add new properties without breaking binary
> > compatibility, due to the use of virtual functions in the frontend.
> 
> Again, please suggest some good ways to do this for the case of
> calendars, where only rather obscure ones have any data; the differences
> among widely-used calendars are all in code.

My preference is the nice-frontend-enum-on-the-backend approach.
 
> > I think in the past we've solved this by having a nice front-end API
> > with non-virtual functions (those we can add) and channeling this
> > through to a backend that uses fewer virtual functions but enums (that
> > can be extended) to dispatch.
> 
> The problem with that is that you're stuck with the calendars that Qt
> ships.  We're never going to ship every calendar that the long tail of
> potential users might want.  We can probably manage the dozen-or-two
> calendars that the ECMAScript spec mentions in this context, but I want
> it to be easy for some minority population to be able to implement their
> own calendar and have Qt transparently use it.  The present design
> supports that.

Why does such a separation impose limitations on the API?
 
> As an example of the long tail, AIUI, a fully faithful implementation of
> the islamic calendar (as distinct from the fairly widely-adopted "civil"
> islamic calendar) needs a distinct calendar for each community.  It
> would, IIUC, need data about the user's (community's) local ephemrides
> (when, exactly, the full or new moon is seen rising there, each month);
> and I want to leave open the option of some population, who want it,
> doing that for themselves without us having to take in patches for them
> to get what they want.  There are likewise variants of the Julian
> calendar still in use by some communities - each its own variant - and I
> want to let them do their thing in their diverse own ways without us
> needing to take in patches.  Then, as alluded to above, there's the
> historians ...
> 
> > Another alternative is the extension mechanism that we've used with
> > QFile/QIODevice.
> 
> I don't know that one.  

It's best demonstrated with the map support in the resource file engine:

    http://code.qt.io/cgit/qt/qtbase.git/tree/src/corelib/io/
qresource.cpp#n1482

A virtual function in the back-end that is lower-level API (not so nice to 
use) but extensible within our constraints. On the frontend the API is nice 
(QFile::map) and it was possible to add this while maintaining binary 
compatibility. It's as if QFile got a new virtual function, except it didn't 
:)

> I just know that there's a bewildering tangle of
> abstractions behind QFile, seemingly to handle different file systems,
> that I sometimes manage to make enough sense of to fix things.  I hope
> we can avoid having such vast complexity for calendars.  They're not
> (individually) actually that complicated (well, except for France and
> Sweden a couple of centuries ago); its the variations between them that
> complicate life.
> 
> All of the extension mechanisms you talk about depend on us writing yet
> another back-end for each supported case.  With calendars, it must be
> possible for some community to support its own, without needing us to
> know about it or do more than provide the infrastructure theirs slots
> into.
>
> So yes, the thing I neglected to mention in my previous mail is: do we
> have any suggestions for how to design an API that'll let app authors
> implement the calendars they want to support (for their possibly very
> minority user-bases) and have them work transparently with Qt, just as
> well as any other calendar that we support ?  Bonus points if there's a
> way for app-authors to implement a plugin API that lets several of them
> share the same plugin-implemented calendars (without us having to care
> how they do it).  The present design does support all of that.
> Using a classic (but not-so-Qt-ish) C++ virtual method API.

I don't see a way around achieving this without Qt declaring an interface that 
contains the features it expects the app author supplied calendar to 
implement.

If we want both, ease of use of calendar API itself as well ease of supplying 
custom calendars to Qt, then we may have to settle for an API that is less 
convenient to use but extensible without breaking source and binary 
compatibility perhaps?

Simon