Re: [Oorexx-devel] A new draft/sketch for documenting the new classes EventSemaphore and MutexSemaphore (Re: A sketch for a documentation text for the "EventSemaphore" class

2019-05-07 Thread Rony G. Flatscher
On 11.04.2019 18:30, Rony G. Flatscher wrote:
>
> This posting was meant to define the documentation for the new Rexx classes 
> EventSemaphore and
> MutexSemaphore.
>
> Just wanted to make sure that it does not get lost, hence the question 
> whether I should submit it
> as some form of a patch?
>
> Also, if I know into which XML-file to place it, I could try to study the 
> existing documentation
> of the classes and the used tags and attributes there and supply also a XML 
> rendering that I would
> think would be appropriate. So please advise.
>
> ---rony
>
You find my attempt at .

---rony




___
Oorexx-devel mailing list
Oorexx-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/oorexx-devel


Re: [Oorexx-devel] A new draft/sketch for documenting the new classes EventSemaphore and MutexSemaphore (Re: A sketch for a documentation text for the "EventSemaphore" class

2019-04-11 Thread Rony G. Flatscher
This posting was meant to define the documentation for the new Rexx classes 
EventSemaphore and
MutexSemaphore.

Just wanted to make sure that it does not get lost, hence the question whether 
I should submit it as
some form of a patch?

Also, if I know into which XML-file to place it, I could try to study the 
existing documentation of
the classes and the used tags and attributes there and supply also a XML 
rendering that I would
think would be appropriate. So please advise.

---rony


On 14.03.2019 20:05, Rony G. Flatscher wrote:
> On 14.03.2019 18:10, Rick McGuire wrote:
>> A couple of notes that need to added to the MutexSemaphore section
>>
>> 1) On a single thread, acquire requests nests, so if a thread calls acquire 
>> again while already
>> having obtained the semaphore, it will be not blocked. It requires an 
>> equivalent number of
>> release calls to free up the mutex. 
>>
>> 2) If the thread holding the mutex ends without releasing the semaphore, the 
>> semaphore will be
>> released automatically.
>>
>> Rick 
>
> Thanks, this version now includes this information in the "acquire" part:
>
> 
> ===
> 5.4.x EventSemaphore Class
>
> Semaphores get used in multithreaded scenarios.
>
> An "event semaphore" allows one thread "A" to synchronize multiple threads
> (like "B", "C", ...) with whom the event semaphore gets shared.  Thread
> "A" creates the event semaphore and sends it the "reset" message.  Then
> thread "A" supplies the event semaphore to the threads "B", "C", ..., each
> of which sends the received event semaphore a "wait" message.  This will
> block the threads "B", "C", ..., until thread "A" sends the "post" message
> to the event semaphore.  At this time all threads waiting on the event
> semaphore get released and can run in parallel on their threads.
>
> 5.4.x.1 close
>
> >>--- close ---><
>
> Closes the event semaphore.
>
>
> 5.4.x.2 isPosted
>
> >>--- isPosted ---><
>
> Returns .true if the event semaphore is in the "posted" state, such that
> sending the "wait" message to this event semaphore would return
> immediately.  A return value of .false indicates that the event semaphore
> is not in the "posted" state, such that a "wait" message will block.
>
>
> 5.4.x.3 post
>
> >>--- post ---><
>
> Sets the event semaphore to the "posted" state, signalling that the event
> that other threads are waiting on has occurred, such that all threads
> waiting on this event semaphore will be released and start to run again.
>
>
> 5.4.x.4 reset
>
> >>--- reset ---><
>
> Resets (clears) the event semaphore to the non-"posted" state, such that 
> "wait"
> messages to this event semaphore will block.
>
>
> 5.4.x.5 uninit
>
> >>--- uninit ---><
>
> This method cleans up the object when it is garbage collected.  It should
> not be invoked directly except via an uninit method of a subclass of the
> EventSemaphore class.
>
>
> 5.4.x.6 wait
>
> >>--- wait(--+-+--)---><
>  | |
>  +-- timeout --+
>
> Waits (blocks) on the event semaphore until it gets "posted".  If the
> optional argument "timeout" was supplied it must be a whole number that
> represents the milliseconds to wait on the event semaphore before
> returning.
>
>
> If no "timeout" value was supplied or its value is negative, the wait will
> be forever, ie. until the event semaphore gets "posted".
>
> If the "timeout" value is zero the method returns immediately with the
> same value that the method "isPosted" would return if sent to the event
> semaphore instead.
>
> The method returns .true if the event semaphore got "posted", .false if
> the method returns prematurely because the given timeout has occurred.
>
>
> Example 5.xxx
>
> The following example will fetch the routine object "WORKER" and in a loop
> will send the routine object the message "start" (defined in the ooRexx
> root class "Object") supplying the message name ("call") to be sent on a
> new (asynchroneous) thread, and as arguments the event semaphore to wait
> on and the number of the loop for the respective asynchroneous message.
>
> The main program creates an event semaphore and sends the message "reset"
> to it.  Then it sends the "start" message three times to the routine
> object in the loop, causing the routine "worker" to run on three different
> threads, where in each thread the executed routine then waits on the event
> semaphore ("wait" message to the event semaphore).  The main program then
> sleeps for five seconds, before sending the "post" message to the event
> semaphore, which will awake the routines on the three threads, ie.  they
> return from the wait message and execute on their 

Re: [Oorexx-devel] A new draft/sketch for documenting the new classes EventSemaphore and MutexSemaphore (Re: A sketch for a documentation text for the "EventSemaphore" class

2019-03-14 Thread Rony G. Flatscher
On 14.03.2019 18:10, Rick McGuire wrote:
> A couple of notes that need to added to the MutexSemaphore section
>
> 1) On a single thread, acquire requests nests, so if a thread calls acquire 
> again while already
> having obtained the semaphore, it will be not blocked. It requires an 
> equivalent number of release
> calls to free up the mutex. 
>
> 2) If the thread holding the mutex ends without releasing the semaphore, the 
> semaphore will be
> released automatically.
>
> Rick 

Thanks, this version now includes this information in the "acquire" part:


===
5.4.x EventSemaphore Class

Semaphores get used in multithreaded scenarios.

An "event semaphore" allows one thread "A" to synchronize multiple threads
(like "B", "C", ...) with whom the event semaphore gets shared.  Thread
"A" creates the event semaphore and sends it the "reset" message.  Then
thread "A" supplies the event semaphore to the threads "B", "C", ..., each
of which sends the received event semaphore a "wait" message.  This will
block the threads "B", "C", ..., until thread "A" sends the "post" message
to the event semaphore.  At this time all threads waiting on the event
semaphore get released and can run in parallel on their threads.

5.4.x.1 close

>>--- close ---><

Closes the event semaphore.


5.4.x.2 isPosted

>>--- isPosted ---><

Returns .true if the event semaphore is in the "posted" state, such that
sending the "wait" message to this event semaphore would return
immediately.  A return value of .false indicates that the event semaphore
is not in the "posted" state, such that a "wait" message will block.


5.4.x.3 post

>>--- post ---><

Sets the event semaphore to the "posted" state, signalling that the event
that other threads are waiting on has occurred, such that all threads
waiting on this event semaphore will be released and start to run again.


5.4.x.4 reset

>>--- reset ---><

Resets (clears) the event semaphore to the non-"posted" state, such that 
"wait"
messages to this event semaphore will block.


5.4.x.5 uninit

>>--- uninit ---><

This method cleans up the object when it is garbage collected.  It should
not be invoked directly except via an uninit method of a subclass of the
EventSemaphore class.


5.4.x.6 wait

>>--- wait(--+-+--)---><
 | |
 +-- timeout --+

Waits (blocks) on the event semaphore until it gets "posted".  If the
optional argument "timeout" was supplied it must be a whole number that
represents the milliseconds to wait on the event semaphore before
returning.


If no "timeout" value was supplied or its value is negative, the wait will
be forever, ie. until the event semaphore gets "posted".

If the "timeout" value is zero the method returns immediately with the
same value that the method "isPosted" would return if sent to the event
semaphore instead.

The method returns .true if the event semaphore got "posted", .false if
the method returns prematurely because the given timeout has occurred.


Example 5.xxx

The following example will fetch the routine object "WORKER" and in a loop
will send the routine object the message "start" (defined in the ooRexx
root class "Object") supplying the message name ("call") to be sent on a
new (asynchroneous) thread, and as arguments the event semaphore to wait
on and the number of the loop for the respective asynchroneous message.

The main program creates an event semaphore and sends the message "reset"
to it.  Then it sends the "start" message three times to the routine
object in the loop, causing the routine "worker" to run on three different
threads, where in each thread the executed routine then waits on the event
semaphore ("wait" message to the event semaphore).  The main program then
sleeps for five seconds, before sending the "post" message to the event
semaphore, which will awake the routines on the three threads, ie.  they
return from the wait message and execute on their threads in parallel,
causing each to sleep for two seconds before returning from the routine
invocation.


eventSem=.eventSemaphore~new  -- create an event semaphore, will be 
in posted state
dt=.dateTime~new -- a .DateTime object to allow measuring 
elapsed time
say "/main\ "  pp(dt~elapsed) "currently 'eventSem~isPosted':" 
pp(eventSem~isPosted)
eventSem~reset   -- reset event semaphore, such that "wait" 
will block
say "/main\ "  pp(dt~elapsed) "after 'eventSem~reset', 
'eventSem~isPosted':" pp(eventSem~isPosted)

w=.routines~waiter   -- get routine 'WAITER' as a routine object
do i=1 to 3
   

Re: [Oorexx-devel] A new draft/sketch for documenting the new classes EventSemaphore and MutexSemaphore (Re: A sketch for a documentation text for the "EventSemaphore" class

2019-03-14 Thread Rick McGuire
A couple of notes that need to added to the MutexSemaphore section

1) On a single thread, acquire requests nests, so if a thread calls acquire
again while already having obtained the semaphore, it will be not blocked.
It requires an equivalent number of release calls to free up the mutex.

2) If the thread holding the mutex ends without releasing the semaphore,
the semaphore will be released automatically.

Rick

On Thu, Mar 14, 2019 at 12:14 PM Rony G. Flatscher 
wrote:

> O.K., got some time for MutexSemaphore and in the course of writing it, I
> corrected the draft for EventSemaphore as well, including the code sample.
>
> Therefore, here the suggestions/drafts for documenting the two classes
> "EventSemaphore" and "MutexSemaphore":
>
> ===
> 5.4.x EventSemaphore Class
>
> Semaphores get used in multithreaded scenarios.
>
> An "event semaphore" allows one thread "A" to synchronize multiple threads
> (like "B", "C", ...) with whom the event semaphore gets shared.  Thread
> "A" creates the event semaphore and sends it the "reset" message.  Then
> thread "A" supplies the event semaphore to the threads "B", "C", ...,
> which each send the received event semaphore a "wait" message.  This will
> block the threads "B", "C", ..., until thread "A" sends the "post" message
> to the event semaphore.  At this time all threads waiting on the event
> semaphore get released and can run in parallel on their threads.
>
> 5.4.x.1 close
>
> >>--- close ---><
>
> Closes the event semaphore.
>
>
> 5.4.x.2 isPosted
>
> >>--- isPosted ---><
>
> Returns .true if the event semaphore is in the "posted" state, such that
> sending the "wait" message to this event semaphore would return
> immediately.  A return value of .false indicates that the event semaphore
> is not in the "posted" state, such that a "wait" message will block.
>
>
> 5.4.x.3 post
>
> >>--- post ---><
>
> Sets the event semaphore to the "posted" state, signalling that the event
> that other threads are waiting on has occurred, such that all threads
> waiting on this event semaphore will be released and start to run again.
>
>
> 5.4.x.4 reset
>
> >>--- reset ---><
>
> Resets (clears) the event semaphore to the non-"posted" state, such that 
> "wait"
> messages to this event semaphore will block.
>
>
> 5.4.x.5 uninit
>
> >>--- uninit ---><
>
> This method cleans up the object when it is garbage collected.  It should
> not be invoked directly except via an uninit method of a subclass of the
> EventSemaphore class.
>
>
> 5.4.x.6 wait
>
> >>--- wait(--+-+--)---><
>  | |
>  +-- timeout --+
>
> Waits (blocks) on the event semaphore until it gets "posted".  If the
> optional argument "timeout" was supplied it must be a whole number that
> represents the milliseconds to wait on the event semaphore before
> returning.
>
>
> If no "timeout" value was supplied or its value is negative, the wait will
> be forever, ie. until the event semaphore gets "posted".
>
> If the "timeout" value is zero the method returns immediately with the
> same value that the method "isPosted" would return if sent to the event
> semaphore instead.
>
> The method returns .true if the event semaphore got "posted", .false if
> the method returns prematurely because the given timeout has occurred.
>
>
> Example 5.xxx
>
> The following example will fetch the routine object "WORKER" and in a loop
> will send the routine object the message "start" (defined in the ooRexx
> root class "Object") supplying the message name ("call") to be sent on a
> new (asynchroneous) thread, and as arguments the event semaphore to wait
> on and the number of the loop for the respective asynchroneous message.
>
> The main program creates an event semaphore and sends the message "reset"
> to it.  Then it sends the "start" message three times to the routine
> object in the loop, causing the routine "worker" to run on three different
> threads, where in each thread the executed routine then waits on the event
> semaphore ("wait" message to the event semaphore).  The main program then
> sleeps for five seconds, before sending the "post" message to the event
> semaphore, which will awake the routines on the three threads, ie.  they
> return from the wait message and execute on their threads in parallel,
> causing each to sleep for two seconds before returning from the routine
> invocation.
>
> 
> eventSem=.eventSemaphore~new  -- create an event semaphore, will be 
> in posted state
> dt=.dateTime~new -- a .DateTime object to allow measuring elapsed 
> time
> say "/main\ "  pp(dt~elapsed) "currently 'eventSem~isPosted':" 
> pp(eventSem~isPosted)
> eventSem~reset   -- reset event semaphore, such that "wait" will 
> block
> say "/main\ "  pp(dt~elapsed) "after 'eventSem~reset', 
> 'eventSem~isPosted':" pp(eventSem~isPosted)
>
> w=.routines~waiter 

[Oorexx-devel] A new draft/sketch for documenting the new classes EventSemaphore and MutexSemaphore (Re: A sketch for a documentation text for the "EventSemaphore" class

2019-03-14 Thread Rony G. Flatscher
O.K., got some time for MutexSemaphore and in the course of writing it, I 
corrected the draft for
EventSemaphore as well, including the code sample.

Therefore, here the suggestions/drafts for documenting the two classes 
"EventSemaphore" and
"MutexSemaphore":


===
5.4.x EventSemaphore Class

Semaphores get used in multithreaded scenarios.

An "event semaphore" allows one thread "A" to synchronize multiple threads
(like "B", "C", ...) with whom the event semaphore gets shared.  Thread
"A" creates the event semaphore and sends it the "reset" message.  Then
thread "A" supplies the event semaphore to the threads "B", "C", ...,
which each send the received event semaphore a "wait" message.  This will
block the threads "B", "C", ..., until thread "A" sends the "post" message
to the event semaphore.  At this time all threads waiting on the event
semaphore get released and can run in parallel on their threads.

5.4.x.1 close

>>--- close ---><

Closes the event semaphore.


5.4.x.2 isPosted

>>--- isPosted ---><

Returns .true if the event semaphore is in the "posted" state, such that
sending the "wait" message to this event semaphore would return
immediately.  A return value of .false indicates that the event semaphore
is not in the "posted" state, such that a "wait" message will block.


5.4.x.3 post

>>--- post ---><

Sets the event semaphore to the "posted" state, signalling that the event
that other threads are waiting on has occurred, such that all threads
waiting on this event semaphore will be released and start to run again.


5.4.x.4 reset

>>--- reset ---><

Resets (clears) the event semaphore to the non-"posted" state, such that 
"wait"
messages to this event semaphore will block.


5.4.x.5 uninit

>>--- uninit ---><

This method cleans up the object when it is garbage collected.  It should
not be invoked directly except via an uninit method of a subclass of the
EventSemaphore class.


5.4.x.6 wait

>>--- wait(--+-+--)---><
 | |
 +-- timeout --+

Waits (blocks) on the event semaphore until it gets "posted".  If the
optional argument "timeout" was supplied it must be a whole number that
represents the milliseconds to wait on the event semaphore before
returning.


If no "timeout" value was supplied or its value is negative, the wait will
be forever, ie. until the event semaphore gets "posted".

If the "timeout" value is zero the method returns immediately with the
same value that the method "isPosted" would return if sent to the event
semaphore instead.

The method returns .true if the event semaphore got "posted", .false if
the method returns prematurely because the given timeout has occurred.


Example 5.xxx

The following example will fetch the routine object "WORKER" and in a loop
will send the routine object the message "start" (defined in the ooRexx
root class "Object") supplying the message name ("call") to be sent on a
new (asynchroneous) thread, and as arguments the event semaphore to wait
on and the number of the loop for the respective asynchroneous message.

The main program creates an event semaphore and sends the message "reset"
to it.  Then it sends the "start" message three times to the routine
object in the loop, causing the routine "worker" to run on three different
threads, where in each thread the executed routine then waits on the event
semaphore ("wait" message to the event semaphore).  The main program then
sleeps for five seconds, before sending the "post" message to the event
semaphore, which will awake the routines on the three threads, ie.  they
return from the wait message and execute on their threads in parallel,
causing each to sleep for two seconds before returning from the routine
invocation.


eventSem=.eventSemaphore~new  -- create an event semaphore, will be 
in posted state
dt=.dateTime~new -- a .DateTime object to allow measuring 
elapsed time
say "/main\ "  pp(dt~elapsed) "currently 'eventSem~isPosted':" 
pp(eventSem~isPosted)
eventSem~reset   -- reset event semaphore, such that "wait" 
will block
say "/main\ "  pp(dt~elapsed) "after 'eventSem~reset', 
'eventSem~isPosted':" pp(eventSem~isPosted)

w=.routines~waiter   -- get routine 'WAITER' as a routine object
do i=1 to 3
   say "/main\ "  pp(dt~elapsed)   "running routine 'WAITER' #" 
pp(i) "asynchroneously"
   w~start("call", eventSem, i)  -- call (run) the routine object 
on a separate thread
end
say

sleepTime=5
say "/main\ "  pp(dt~elapsed)