Hi experts,

As I am not familiar with the appropriate tools and the proceedings, I'd like to request a knowledgeable person to enhance the docs for some RTL functions that might get rather important to me in the future:

1) http://www.freepascal.org/docs-html/rtl/classes/checksynchronize.html

IMHO this is not a documentation at all but just a vague hit on how this function might be used.

I think a more appropriate description could be similar to

------------------------------------------------------------------------ *CheckSynchronize **checks if there are entries in the event queue, pulls them and fires events (aka callbacks) for each of them until the event queue is empty. **
**
**The Events **CheckSynchronize **pulls from the queue have been generated by **TThread.Synchronize
<http://www.freepascal.org/docs-html/rtl/classes/tthread.html>**and TThread.Queue calls. **
**
**Calling **CheckSynchronize**is only allowed in the Main thread, but not ion worker threads generated by TThread siblings.*

CheckSynchronize should be called regularly by the main application thread to handle any TThread.Synchronize
<http://www.freepascal.org/docs-html/rtl/classes/tthread.html>*and TThread.Queue* calls that may be waiting for execution by the main thread. ------------------------------------------------------------------------

2) http://www.freepascal.org/docs-html/rtl/classes/wakemainthread.html

------------------------------------------------------------------------ WakeMainThread is called by the TThread.synchronize <http://www.freepascal.org/docs-html/rtl/classes/tthread.html>*and the TThread.Queue* call. ,,,,
(In fact I don't really understand the rest of the text, but that might be my own silliness. Of course I do know exactly what WakeMainThread is supposed to do.)
------------------------------------------------------------------------

3) http://www.freepascal.org/docs-html/rtl/classes/tthread.html

- The function Synchronize is missing even though
http://www.freepascal.org/docs-html/rtl/classes/checksynchronize.html links here on that behalf
- the function Queue is missing (which of course has been implemented only recently)

Thanks a lot !

-Michael

Please report a bug in project FPC for category Documentation. This way it won't be forgotten.

Regards,
Sven

sorry I forgot:

*If the event queue is empty, **CheckSynchronize w**aits for an event to be pushed by a TThread or for /timeout/ Milliseconds to pass. If timeout is 0, it waits forever.*

(Of course it should be documented whether or not the function returns if some events have been handled but the timeout did not hit. I don't know if this is the case.)

-Michael

Michael Schnell wrote

*If the event queue is empty, **CheckSynchronize w**aits for an event to be pushed by a TThread or for /timeout/ Milliseconds to pass. If timeout is 0, it waits forever.*

In the context of a wait a wait forever given a value of naught , this is pretty much the standard. In any language, in any OS. Why document a given?

Thaddy wrote

Why document a given?

A timeout = 0 can mean either of

"Wait up to forever but return when something happens" or

"Do what is to do and return at once even if there is nothing to do " or

"Never Return. When something happens do the appropriate and go on waiting for the next"

I saw all three variants in some libraries.

Also sometimes a value of -1 or $FFFFFFFF denotes one of the three alternatives.

A "normal" number can mean:

"return if something happens or the timeout is hit" or

"Stay in the function until the timeout is hit and during that time do what is to be done" (rather unusual but not completely senseless.)

-Michael

Al 18/09/13 10:08, En/na Michael Schnell ha escrit:

If timeout is 0 it won't wait at all:

        if timeout>0 then
          begin
            RtlEventWaitFor(SynchronizeTimeoutEvent,timeout);
          end
         else
           RtlEventResetEvent(SynchronizeTimeoutEvent);

Bye

Luca Olivetti wrote

If timeout is 0 it won't wait at all:

Thanks for the correction.

(So "Wait forever" is not implemented.)

I'll include that in the report I'm going to file in Mantis.

-Michael

Al 18/09/13 11:55, En/na Luca Olivetti ha escrit:

BTW, while I agree that there's no substitute for good documentation, when you have the source you can easily solve your doubts about some implementation details.
With lazarus it's even easier:

1) Project->New project->Application
2) double click on the newly created form
3) in the event that 3) creates type "CheckSynchronize"
4) Put your mouse over "CheckSynchronize", press CTRL and click. This will lead to the declaration of "CheckSynchronize"
5) From there, press CTRL+SHIFT+DOWN (i.e.arrow down) and you can see the implementation
6) Rinse and repeat for every call you have some doubts about, to backtrack you can use CTRL+H

Bye

Luca Olivetti wrote

With lazarus it's even easier :...

Without this I would never had a running project ever :-)

-Michael

Sven Barth wrote

Please report a bug in project FPC for category Documentation. This way it won't be forgotten.

Done: 0025056 <http://mantis.freepascal.org/view.php?id=25056>

-Michael