In OpenKODE 1.0.2 specification 8.4.5 kdInstallCallback
It is unclear to me if eventuserptr is also set to KDEvent.userptr when the callback is called.
If yes, then is userptr changed before calling the callback in the case when I registered two callbacks with the same event but different userptrs?
In addition: what happens if I set a timer via kdSetTimer and listen to the event via kdInstallCallback.
In this case I have two eventuserptr. One from SetTimer and one from InstallCallback.
The spec says:
This function installs or removes a callback function for a
particular set of event type and user pointer combinations,
as specified by the eventtype and eventuserptr parameters.
Setting eventtype to 0 matches any event type,
including event type 0. Setting eventuserptr to KD_NULL
matches any user pointer, including KD_NULL.
So the eventuserptr you give to kdInstallCallback helps to determine which events are handled by your new callback. Your callback will only be called for an event whose userptr has the value you specify in kdInstallCallback (unless you specify KD_NULL, in which case it is called for any userptr).
The event's userptr is not explicitly set to the eventuserptr value supplied to kdInstallCallback, although it will have the same value because of the above matching process, unless you gave a value of KD_NULL to kdInstallCallback.
Do you have any suggestion on how to make this clearer for people reading the spec ?
that clears it up but also makes it a lot more difficult to use as e.g. an application could catch timer events that were intended for a library it uses by just registering a callback.
If the application sticks to registering specific eventuserptrs in its own callbacks, then there is no danger, because the application won't know the library's userptr to override it. If I'm interpreting the spec correctly, then there is a danger of this if the application specifies KD_NULL as the userptr, since this overrides any more specific pointers provided for a given event type. It might have been better had KD_NULL been to defined to match any events for which a more specific callback doesn't already exist, rather than all events. (I.e., a default, rather than an override.)
However, that said, if a library is registering callbacks within an application thread, then it is already making assumptions that either: the application will at some point call an event pumping function so that these events are processed; or they will be processed when a subsequent library call is made, and that it is safe for any of the application's registered callbacks to be handled at that time as well. This implies at least a mimimal level of cooperation/coordination between library and application when it comes to event handling, and it is not unreasonable to assume that they will know enough not to stomp on each other. If a library needs to have events automatically handled without any coordination with the application, it should probably spawn its own separate thread in which to process these events.
> If the application sticks to registering specific eventuserptrs in its own
> callbacks, then there is no danger, because the application won't know the
> library's userptr to override it.
Yes, as long as everyone is using a pointer to some memory they own as the eventuserptr, so there is no clash.
Ralf, are you happy with this, or do you think there should be some clarification to the text ?
-Tim Renouf, OpenKODE spec editor
The description of userptr in 8.3.1 is a little unclear even after your explanation. Actually the use of it is only clear after I already know it.
Maybe mentioning global events and kdSetEventUserptr at this place would help.
How about if we add to the end of the first paragraph in the Description section, repeating a bit of 8.3.1:
The user pointer of an event was provided by the application to the API
that generates the event. Each event type documents where its userptr
value comes from.
This doesn't explicitly mention global events, but if you look at the documentation for a particular global event it does tell you the userptr comes from kdSetEventUserptr.
Is that any better ?