Problems related to Caja.OperationResult.IN_PROGRESS and some others

[monnerat]

This is a request for comments. There are several discrepancies in the current master: I would like to fix them but there are more than one way of doing it, all having their drawbacks. I would like to get your opinion on these. Forgive me: I know this text is a bit long.

Caja.OperationResult.IN_PROGRESS

Here is a list of related problems:

1) file info updates are serialized.

While a file information info request is in progress, Caja is responsive to navigation, but does not schedule another file information request until the current one is complete or cancelled: this tends to slow down the displayed items info availability even if the extension is able to process several info update requests in parallel. This is not a python-caja problem and is completely under the responsibility of Caja itself (even the C extensions are affected).

2) Caja.OperationHandle is not alterable

When Caja.update_file_info_full() returns Caja.OperationResult.IN_PROGRESS, the Caja C API expects the handle parameter to have been set by the extension to a non-NULL gpointer value. Python-caja does not set this value and uses an undefined value (often NULL) to build the handle object passed to the Python method: this is a python-caja bug. Please note that leaving the handle to a NULL value may fool Caja into "thinking" nothing is in progress at some levels.
There are 2 solutions to this problem:
a) Generate a dummy gpointer from a counter, store it in the C API's handle and pass it to Caja.update_file_info_full(). This has the advantage of not fooling Caja and retaining the Python method signature, but does not give handle control to the Python extension. This is the minimum fix needed in python-caja.
b) Do as a) for a default handle value and provide an API that can change a Caja.OperationHandle value, give this value to the C API upon return. This allows controlling the handle by the Python extension, but will probably require support from Caja itself.

3) Caja.OperationHandle is not serializable

The handle is supposed to identify some data associated with the request, but cannot be used as a dictionary key in Python without an awful hack on its string representation. It thus cannot be used by a Python extension for its original purpose of locating extension data. Unfortunately, there is no solution that can be implemented in python-caja: Caja itself ought to provide a serialization API for an OperationHandle.

4) cancel_update() implementation is currently mandatory

If Caja navigation changes displayed directory while a file info update is in progress, Caja calls method cancel_update(). A base class method is provided as Caja.InfoProvider.cancel_update(self, handle), while python-caja calls it as Caja.InfoProvider.cancel_update(self, provider, handle). This is
a python-caja bug (bad implementation) that can hardly be fixed without altering the requested method signature. An immediate solution is to always implement cancel_update() if there are risks of this situation in a Python extension: this does not break existing extensions but introduces a stupid constraint.

Most of these problems probably existed before the python-caja fork, and still exist in the original project.

By googling around, I have not found a single open-source real Caja Python extension that uses Caja.OperationResult.IN_PROGRESS: this comforts me into thinking it is hardly usable and we may alter the methods signature with a very little impact, if some.

RabbitVCS uses its own implementation for handling asynchronous updates, mainly because of problem 1), thus avoiding all the other problems: see http://wiki.rabbitvcs.org/wiki/development/nautilus-probs). With regards to all above, I would advice to do so.

As we are supposed to properly support our features, the above points should find a real solution in one way or another:

• Are we allowed to alter prototype signatures?
• Do we minimally fix existing API and provide an alternate one?
• Can we consider additional support in Caja itself?

As a base of investigations for this document, I have spent a lot of time in examining definitions in the generated file /usr/share/gir-1.0/Caja-2.0.gir, mainly about which and how definitions are enforced: I noted the following discrepancies: they are not all related to Caja.OperationResult.IN_PROGRESS but may also involve methods signature changes:

• Caja.InfoProvider.update_file_info_full(): python-caja calls it as instance method Caja.InfoProvider.update_file_info_full(provider, handle, closure, file) while provider is already available as the instance itself. Although not causing any problem, the signature should be simplified into Caja.InfoProvider.update_file_info_full(handle, closure, file)
• Caja.InfoProvider.cancel_update(): likewise. See problem 4).
• Caja.info_provider_update_complete_invoke(): the documentation is wrong: should read Caja.info_provider_update_complete_invoke(closure, provider, handle, result), with no default value for the result parameter. Has now even be cloned as @staticmethod Caja.InfoProvider.update_complete_invoke(closure, provider, handle, result).
• Caja.MenuProvider.get_file_items_full() and Caja.MenuProvider.get_background_items_full(): no problem here, but methods are useless: provider is already given as the instance itself.
• Caja.menu_provider_emit_items_updated_signal(): documentation wrong: renamed Caja.MenuProvider.emit_items_updated_signal() with the provider taken from the instance.
• Caja.PropertyPageProvider.get_pages(): documentation or implementation wrong: although named as such in the C API and gir definitions, Python Caja extensions have to name this method get_property_pages() or else it won't be called.

Thanks for reading and commenting

[raveit65]

@mate-desktop/core-team
thoughts?