[PD] documenting messages to/from Pd and dynamic patching

[Christof Ressi]

> (I forgot why they are "illegal"), 
They are not "illegal", they are private. As I tried to explain in the 
last mail, messages like "donecanvasdialog" or "mouseup" are used for Pd 
core <-> GUI communication. The only reason why they exist in the first 
place is because Pd core and GUI live in different processes, otherwise 
they could simply be C function calls.

The nice thing about a private API is that you can change/extend it at 
will. Once the private API becomes public, this becomes hard or even 
impossible.

Now, the problem with Pd is that it doesn't really have a mechanism to 
prevent users from calling those internal messages. (The only exception 
being the "dsp" method.)

> and when possible new methods should come out to replace them. 
I think that's where we should put our focus on. Things like emulating 
mouse interaction by sending "mouse" and "mouseup" messages are a huge 
red flag. The user is obviously trying to achieve something and we 
should ask ourselves what it is exactly and how this could be done in a 
more sane way. So maybe a good start would be to collect different 
dynamic patching use cases and then think about possible new APIs that 
could help achieve them.

My "goprect" PR is just one step in this direction.

[iemguts] is also a good example of this approach: it basically provides 
a stable public API over a unstable private APIs. The advantage is that 
whenever Pd changes the implementation, only [iemguts] needs to be 
updated, instead of every patch that directly uses the internal message. 
For example, with [iemguts] there really is no reason to ever use 
"mouse" and "mouseup" again. Unfortunately, many people seem to prefer 
undocumented internal messages over a well tested external...

Christof

On 27.11.2021 14:32, João Pais wrote:
>
>>> but I've been using them for more than 15 years with no big issues.
>> Well, a few years ago Miller changed the [donecanvasdialog( message. 
>> I noticed that it will break dynamic patching and asked him to use a 
>> workaround. He was nice enough to do it. So you were just lucky ;-)
>>
>> Note that the messages found in Pd patch files, like [obj ...(, are 
>> pretty stable. We can't really change them without breaking literally 
>> all existing patches. However, anything else should really be 
>> considered private. Particularly mnssages like [mouse(, [mouseup(, 
>> [donecanvasdialog( are obviously internal messages sent between Pd 
>> core and the GUI process. People just discovered them in the source 
>> code (or by watching the GUI/Pd traffic) and started (ab)using them 
>> for dynamic patching. The Pd extended folks included them in their 
>> documentation, so usage became more wide-spread. However, it was 
>> never officially supported in Pd vanilla.
>>
> yes, at some point it would be good to assume that they can stay and 
> keep being abused (I forgot why they are "illegal"), and when possible 
> new methods should come out to replace them.
>