--- a/JavaMonitor.st	Sat Aug 12 22:11:28 2017 +0100
+++ b/JavaMonitor.st	Fri Aug 25 12:31:16 2017 +0100
@@ -170,6 +170,10 @@
 !JavaMonitor methodsFor:'public'!
 
 acquire
+    "Acquire (enter) the monitor and return `true`.
+
+     See JVM spec, section 4.5, MONITORENTER.
+    "
     | thisProcess wasBlocked hasAcquired |
     hasAcquired := nil.
     thisProcess := Processor activeProcess.
@@ -208,73 +212,96 @@
 
     "Created: / 20-11-2011 / 13:21:46 / Marcel Hlopko <hlopkmar@fel.cvut.cz>"
     "Modified: / 11-08-2017 / 22:08:16 / Jan Vrany <jan.vrany@fit.cvut.cz>"
+    "Modified (comment): / 14-08-2017 / 09:34:16 / Jan Vrany <jan.vrany@fit.cvut.cz>"
 !
 
 enter
-    self acquire.
+    <resource: #obsolete>
+    self obsoleteMethodWarning: 'Use #acquire instead'.     
+    ^ self acquire.
 
     "Created: / 20-11-2011 / 13:21:42 / Marcel Hlopko <hlopkmar@fel.cvut.cz>"
-    "Modified: / 03-06-2017 / 23:11:03 / Jan Vrany <jan.vrany@fit.cvut.cz>"
+    "Modified: / 14-08-2017 / 10:20:31 / Jan Vrany <jan.vrany@fit.cvut.cz>"
 !
 
 exit
-    | thisProcess |
-
-    "JV@2017-06-03: Question: Is it legal (i.e., is the good reason to) call #exit 
-     on a monitor by a process that does not own it? Shouldn't we rather throw an 
-     error"
-    thisProcess := Processor activeProcess.
-    owningProcess == thisProcess ifTrue: [ self release. ].
+    <resource: #obsolete>
+    self obsoleteMethodWarning: 'Use #release instead'.     
+    ^ self release.
 
     "Created: / 20-11-2011 / 13:21:54 / Marcel Hlopko <hlopkmar@fel.cvut.cz>"
-    "Modified: / 12-08-2017 / 21:27:16 / Jan Vrany <jan.vrany@fit.cvut.cz>"
+    "Modified: / 14-08-2017 / 10:20:43 / Jan Vrany <jan.vrany@fit.cvut.cz>"
 !
 
 notify
-    "wakeup one waiting process"
+    <resource: #obsolete>
+    self obsoleteMethodWarning: 'Use `notify: false` instead'.
+    ^ self notify: false.
+
+    "Created: / 22-11-2011 / 12:14:23 / Marcel Hlopko <hlopkmar@fel.cvut.cz>"
+    "Modified: / 14-08-2017 / 10:19:59 / Jan Vrany <jan.vrany@fit.cvut.cz>"
+!
+
+notify: all
+    "
+    An implementation of java.lang.Object#notify() and #notifyAll(). If `all` is
+    `true` then all waiting threads are notified (see #norifyAll()) otherwise only
+    one thread is notified (see #notify()). Returns `true` after when threads have 
+    been notified or `false` if calling thread does not own the monitor.
+
+    See Java API documentation for java.lang.Object#notify() and #notifyAll().
+        https://docs.oracle.com/javase/7/docs/api/java/lang/Object.html#notify()
+        https://docs.oracle.com/javase/7/docs/api/java/lang/Object.html#notifyAll()
+    "
     
     | thisProcess |
     thisProcess := Processor activeProcess.
-    self assert: owningProcess == thisProcess.
+    owningProcess == thisProcess ifFalse:[ 
+        "/ Oops,  calling thread does not own the monitor. return false
+        "/ immediately. The caller is responsible for throwing
+        "/ IllegalMonitorStateException...
+        ^ false.
+    ].
     JavaVM monitorTrace ifTrue:[
         Logger 
-            log: ('%1: notifying %2 processes' bindWith: thisProcess printString
+            log: ('%1: notifying %1%2 processes' bindWith: thisProcess printString
+                    with: (all ifTrue:[ 'all ' ] ifFalse:[ '' ])
                     with: waitingSema waitingProcesses size)
             severity: Logger severityDEBUG
             facility: #JVM.
     ].
-    waitingSema signal.
+    all ifTrue:[ waitingSema signalForAll ] ifFalse:[ waitingSema signal ].
     Processor yield.
+    ^ true
 
-    "Created: / 22-11-2011 / 12:14:23 / Marcel Hlopko <hlopkmar@fel.cvut.cz>"
-    "Modified: / 11-08-2017 / 22:25:44 / Jan Vrany <jan.vrany@fit.cvut.cz>"
+    "Created: / 14-08-2017 / 10:17:20 / Jan Vrany <jan.vrany@fit.cvut.cz>"
 !
 
 notifyAll
-    "wakeup one waiting process"
-    
-    | thisProcess |
-    thisProcess := Processor activeProcess.
-    self assert: owningProcess == thisProcess.
-    JavaVM monitorTrace ifTrue:[
-        Logger 
-            log: ('%1: notifying all %2 processes' bindWith: thisProcess printString
-                    with: waitingSema waitingProcesses size)
-            severity: Logger severityDEBUG
-            facility: #JVM.
-    ].
-    waitingSema signalForAll.
-    Processor yield.
+    <resource: #obsolete>
+    self obsoleteMethodWarning: 'Use `notify: true` instead'.
+    ^ self notify: true.
 
     "Created: / 22-11-2011 / 12:14:36 / Marcel Hlopko <hlopkmar@fel.cvut.cz>"
-    "Modified: / 11-08-2017 / 22:26:01 / Jan Vrany <jan.vrany@fit.cvut.cz>"
+    "Modified: / 14-08-2017 / 10:19:47 / Jan Vrany <jan.vrany@fit.cvut.cz>"
 !
 
 release
+    "Release (leave) the monitor and return `true` if
+     monitor was release, `false` if monitor has not
+     been released (because calling thread does not own it).
+
+     See JVM spec, section 4.5, MONITOREXIT.       
+    "
     | thisProcess wasBlocked |
 
     thisProcess := Processor activeProcess.
-    self assert: owningProcess == thisProcess.
+    owningProcess == thisProcess ifFalse:[ 
+        "/ Oops,  calling thread does not own the monitor. return false
+        "/ immediately. The caller is responsible for throwing
+        "/ IllegalMonitorStateException...
+        ^ false.
+    ].
     wasBlocked := OperatingSystem blockInterrupts.
     count == 1 ifTrue:[ 
         owningProcess := nil.
@@ -284,25 +311,40 @@
         count := count - 1.
     ].
     wasBlocked ifFalse:[ OperatingSystem unblockInterrupts ].
+    ^ true
 
     "Created: / 20-11-2011 / 13:21:52 / Marcel Hlopko <hlopkmar@fel.cvut.cz>"
     "Modified: / 12-08-2017 / 21:28:38 / Jan Vrany <jan.vrany@fit.cvut.cz>"
+    "Modified (comment): / 14-08-2017 / 09:35:36 / Jan Vrany <jan.vrany@fit.cvut.cz>"
 !
 
 wait
-    "make owning process to go to wait"
-    
-    self waitForMilliseconds: nil.
+    <resource: #obsolete>    
+    self obsoleteFeatureWarning: 'Use `waitForMilliseconds: nil` insteead'.        
+    ^ self waitForMilliseconds: nil.
 
     "Created: / 22-11-2011 / 11:57:56 / Marcel Hlopko <hlopkmar@fel.cvut.cz>"
+    "Modified: / 14-08-2017 / 09:37:18 / Jan Vrany <jan.vrany@fit.cvut.cz>"
 !
 
 waitForMilliseconds: timeOut 
-    "make owning process to go to wait, but not longer than timeout"
+    "
+    An implementation of java.lang.Object#wait(long). Returns `true`
+    after waiting or `false` immediately (i.e., won't block) if calling
+    thread does not own the monitor.
+
+    See Java API documentation for java.lang.Object#wait(long):
+        https://docs.oracle.com/javase/7/docs/api/java/lang/Object.html#wait(long)
+    "
     
     | thisProcess countBeforeWait |
     thisProcess := Processor activeProcess.
-    self assert: owningProcess == thisProcess.
+    owningProcess == thisProcess ifFalse:[ 
+        "/ Oops,  calling thread does not own the monitor. return false
+        "/ immediately. The caller is responsible for throwing
+        "/ IllegalMonitorStateException...
+        ^ false.
+    ].
     self waitEnabled ifFalse: [
         JavaVM monitorTrace ifTrue:[
             Logger 
@@ -312,7 +354,7 @@
                 severity: Logger severityDEBUG
                 facility: #JVM.
         ].
-        ^ self.
+        ^ true.
     ].
     JavaVM monitorTrace ifTrue:[
         Logger 
@@ -343,11 +385,12 @@
     ].
     "/ We have been notified, re-acquire the monitor
     self acquire.
-    count := countBeforeWait. "/ note that at this point we already own the monitor
+    count := countBeforeWait. "/ note that at this point we already own the monitor.
+    ^ true.
 
     "Created: / 22-11-2011 / 12:52:45 / Marcel Hlopko <hlopkmar@fel.cvut.cz>"
     "Modified: / 01-12-2011 / 10:57:52 / Marcel Hlopko <hlopkmar@fel.cvut.cz>"
-    "Modified: / 11-08-2017 / 23:04:45 / Jan Vrany <jan.vrany@fit.cvut.cz>"
+    "Modified (comment): / 14-08-2017 / 09:52:06 / Jan Vrany <jan.vrany@fit.cvut.cz>"
 ! !
 
 !JavaMonitor methodsFor:'queries'!