============================================================================= CSP for Java : JCSP 1.1 Release Candidate 1 (rc4) ============================================================================= This file contains: o the manifest list of files/directories in this release; o installation notes; o incremental change list since JCSP 0.5. Please read the GNU-LGPL-2.1.txt file. Retention of these files is assumed to imply acceptance of the terms in that license. This release is licenced under the Lesser GNU Public Licence, version 2.1 (LGPL 2.1). A copy is included with the distribution, or you can read an online version at: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html There are rather a lot of deprecated items now in the library. Most of these will be removed in JCSP 1.2. This vew version will contain a completely re-written networking support (org.jcsp.lang.channel). Peter Welch and Neil Brown. (28th. November, 2008) ============================================================================= JCSP 1.1 (rc4) Manifest ============================================================================= jcsp.jar (class library containing all features, both net and core - add either this, or jcsp-core.jar, to your CLASSPATH) jcsp-core.jar (class library containing just the core features - add either this or jcsp.jar to your CLASSPATH) Note: jcsp-core excludes the networking mechanisms (and some other things) contained within jcsp.jar. It is a smaller library for applications running in a single JVM. It efficiently exploits multicore processors. jcsp-demos/ (directory with sources for lots of demos) jcsp-demos-util.jar (addtional class library - needed for the demos) jcsp-doc/ (javadoc HTML tree for jcsp.jar) jcsp-core-doc/ (javadoc HTML tree for jcsp-core.jar) Note: the jcsp-core-doc folder is included so that jcsp-core users are not overloaded with materials they do not use. For either of the above trees, point your browser at the index.html file at their top level. GNU-LGPL-2.1 (open source licence agreement) README-JCSP-1.1-rc4.txt (this file) L-GPL open sources are available from the subversion repository: svn checkout http://projects.cs.kent.ac.uk/projects/jcsp/svn/jcsp/tags/jcsp-1.1-rc4/ You will need the JDK1.3 libraries (or any later JDK) installed to work with the JCSP library. ============================================================================= Installation Notes ============================================================================= Put the file jcsp.jar (or jcsp-core.jar) in your CLASSPATH. You do *not* need to unpack these files. Point your web browser at (and, maybe, bookmark): jcsp-doc/index.html or jcsp-core-doc/index.html for the documentation to the JCSP library. The jcsp-demos directory contains many JCSP demonstration applications and applets. These are not embedded in any Java packages. Each demo is contained in a single sub-directory. To run one, change to that directory, compile (javac *java) and run the main program (which usually has the word "Main" as part of its name). ============================================================================= Change List ============================================================================= Changes since JCSP 1.1 (rc3) release ------------------------------------ At last, the documentation has been changed to conform to the API changes introduced in version 1.1. Many minor bugs fixed. Some new demos added. The documentation of org.jcsp.lang.Channel (from which all channels should be made) and org.jcsp.lang.Poisonable (for simplifying network shut-down) has been finished. There are rather a lot of deprecated items now in the library. Most of these will be removed in JCSP 1.2. This vew version will contain a completely re-written networking support (org.jcsp.lang.channel). Peter Welch and Neil Brown. (28th. November, 2008) Changes since JCSP 1.1 (rc2) release ------------------------------------ Deprecated the remaining old methods of channel creation and fixed some public visibility mistakes. Neil Brown and Peter Welch. (3rd. March, 2008). Changes since JCSP 1.1 (rc1) release ------------------------------------ Deprecated some of the channel factories, and updated the overview of the documentation and this README file. Neil Brown and Peter Welch. (9th. October, 2007). Changes since JCSP 1.0 (rc8) release ------------------------------------ The library has been merged with the old Quickstone version, which includes a great many changes. The channels are now interfaces with hidden implementations, and must be created using methods in the Channel class. The networking aspects from Quickstone's JCSP.NET have been included. Poisonable channels are now included. Many Quickstone classes have been removed (from JCSP.NET; JCSP core users will not notice any difference) or deprecated ready for future removal. Symmetric Object channels have been added. Neil Brown and Peter Welch. (5th. October, 2007). Changes since JCSP 1.0 (rc7) release ------------------------------------ Symmetric channels (One2OneChannelSymmetricInt) added, with demo added to CommsTime (to run with symmetric channels) and a new output-guards demo folder. Peter Welch. (16th. August, 2007) Changes since JCSP 1.0 (rc6) release ------------------------------------ One correction to AltingBarrier. Lots more documentation and examples for AltingBarrier. Minor documentation improvements elsewhere. Some Framed* classes added to jcsp.plugNplay. These wrap some jcsp.awt Active* widgets (buttoms and scrollbars) in frames for immediate use. They are useful for quick demonstrations (and used in the documentation of AltingBarrier). The Parallel class has a new contructor taking a 2D-array of processes. Spurious wakeup protection/logging has been added to the Bucket and Stop classes. These has been overlooked when preparing the rc6 version. Peter Welch. (19th. December, 2006) Changes since JCSP 1.0 (rc5) release ------------------------------------ The introduction of an (experimental) AltingBarrier class. This is a Guard useable for Alternative selections. It implements multiway synchronisation (i.e. a CSP 'event'), allowing all parties to back off choice operations. One party to the AltingBarrier will select it if and only if *all* parties select it. Prioritised choice is not allowed if the choice includes an AltingBarrier, since conflicting priorities would be easy to set up and impossible to resolve. Fair choice is allowed, but only on the understanding that a completed AltingBarrier takes precedence over other typse of Guard (because of the necessity for all parties to the choice making the same one). The Alternative class has had to be modified to support AltingBarriers. This should have negligeable overhead on its operation without AltingBarriers. An AlternativeError class has been added, which is thrown in the attempt to make a prioritised choice over a set of Guards including an AltingBarrier. A JCSP_InternalError class has been added. This is thrown if an internal inconsistency is detected. Currently, this is used for defensive programming only of the AltingBarrier (which, we stress, is experimental). Spurious wakeup protection has been added to all blocking methods (channel communications, barrier synchronisation, alting, etc.). These are implemented with invocations of "Object.wait()". The Java specification has always included a footnote that those calls may "spuriously" return for no proper reason (where "proper" means being released through an "Object.notify()", "Object.notifyAll()", an "InterruptedException" or a timeout)! There was no mention of this danger in the (javadoc) documentation in JDK 1.3 and earlier versions. The danger is heavily emphasised in the documentation for JDK 1.5, so we thought we should take it seriously. Spurious wakeup protection requires a few extra fields in some of the classes and extra work (and ugly code) at run-time -- but these overheads are pretty slight. Optional logging of detected spurious wakeups is provided (see the "SpuriousLog"). Running stress tests on Sun's JVMs, with logging switched on, has *never* shown any! It has long been known that "early" timeouts (from "Object.wait(long)") occur and JCSP has always allowed them. The above logging mechanism also reports counts of these -- and they occur frequently. The acceptable margin for "early" timeouts may be set by "SpuriousLog.setEarlyTimeout(long)"; by default, that margin is set to 9 milliseconds (which covers most of those encountered using Sun's JVMs). Timeouts returning earlier than the acceptable margin are treated as spurious wakeups and the timeout is reset. A margin of zero may be defined, but that would lead to many re-timeouts that are not really needed -- note that JCSP running on standard JVMs should not be used for critical ("hard") real-time applications. Peter Welch. (6th. January, 2006) and (19th. December, 2006) Changes since JCSP 1.0 (rc4) release ------------------------------------ First, many apologies for the long interval sine the last release. We are very positive about this work, but have been concentrating our time on developing the occam-pi language and supporting infrastructure. occam-pi and JCSP are closely related - common goals, differing technologies. Anyone interested in finding more about occam-pi, please check out: http://www.cs.kent.ac.uk/projects/ofa/kroc/ (motivation and download) http://frmb.org/occ21-extensions.html (summary of extensions over occam2.1) http://rmox.net/prelude/ (experimental OS) Back to JCSP! This release is mostly just maintenance over rc4, with several sets of classes re-implemented for better efficiency and security (i.e. no semantic change). Some changes have been made though: o several more items have been deprecated: interfaces: jcsp.lang.Channel, jcsp.lang.ChannelInt. Note: these are just the union of their separate input/output classes: jcsp.lang.Channel = jcsp.lang.ChannelInput union jcsp.lang.ChannelOutput jcsp.lang.ChannelInt = jcsp.lang.ChannelInputInt union jcsp.lang.ChannelOutputInt They are never needed! Such interfaces are used for the parameters of CSProcess class constructors and should only hold one end (either input ot output, but not both!) of the channel plugged in to any given instance. Any other use is misconceived. We are afraid that some pieces of JCSP documentation incorrectly used these interfaces. This have been corrected in this release. abstract classes: jcsp.lang.AltingChannel, jcsp.lang.AltingChannelInt. Note: these are deprecated for exactly the same reasons as above. Use AltingChannelInput, respectively AltingChannelInputInt, instead for input channels that need to support ALTing - or ChannelOutput, respectively ChannelOutputInt, for output channels. General note about the above deprecated items: THEY WILL BE REMOVED from the final 1.0 release! That will be a merger with the full JCSP Network Edition i from Quickstone (http://www.quickstone.com/xcsp/jcspnetworkedition/). This has a cleaner (more systematic) way for creating the wide variety of channels supported and we want the name "Channel" as the right name for the class of static `factory' methods. Other changes: o a bunch of deprecated items have now been removed: methods: jcsp.lang.Alternative.select (AltingChannelInput[], ...) etc.. Note: Alternative classes *must* now be constructed bound to their Guard arrays - so there is no need to suppy those to their select methods. constructors: jcsp.lang.Alternative (). Note: use jcsp.lang.Alternative (Guard[] guard) instead - see above. constructors: jcsp.lang.Any2AnyChannel(ChannelDataStore) etc.. Note: all deprecated channel constructors taking ChannelDataStore or ChannelDataStoreInt have been removed. Use the static create methods instead. This removal was needed for technical reasons for improving the efiiciency of default channels (i.e. those without ChannelDataStore buffers). As mentioned in the "General note" above, all channel creation in future releases will be via the Channel static create methods. o a bug fix: class: jcsp.lang.Stop. Note: this simple class was included for completeness - it is one of the primitives of CSP. It never occurred to us that anyone would need to use it and it was never tested! But someone did use it. It carried a very stupid bug - now exterminated. Peter Welch (5th. September, 2005) Changes since JCSP 1.0 (rc3) release ------------------------------------ o Minor corrections and changes to a (very) few of the documentation files. o A new demo - MultiPong :-) o A modified demo - Infection. This has more controls and interaction. See how hard it is fighting (say) Foot-and-Mouth by culling neighbouring animals when the effectiveness of the cull is only 99% ... Peter Welch. (13th. July, 2001) Changes since JCSP 1.0 (rc2) release ------------------------------------ o Fixed bug in jcsp.util.Buffer and jcsp.util.ints.BufferInt. When we tried to create a buffered channel of size n, we used to get one of size (n+1). The channel buffer is now created correctly with the requested size. o Fixed bug in jcsp.awt.GraphicsCommand.DrawArc and jcsp.awt.GraphicsCommand.FillArc. A typing error had omitted startAngle and arcAngle from the constructor's parameter list. It compiled OK under JDK1.2 (but couldn't work correctly). The JDK1.3 compiler was more thorough and, quite properly, rejected it. All is well now. o Several additions to the documentation. In particular, the top-level javadoc page points new users to the documentation in the jcsp.lang.CSProcess interface - where there is an overview of (Communicating Sequential) Process Oriented Design and the implementation pattern for a JCSP process. o Modified Binary Code License (that explicitly allows redistribution of JCSP classes as part of users' applications/applets). Peter Welch. (7th. February, 2001) Changes since JCSP 1.0 (rc1) release ------------------------------------ o Change of name of the "Timer" class in jcsp.lang to "CSTimer". This has been caused by the JDK1.3 release from Sun introducing their own classes called "Timer" in packages java.util and javax.swing. Without this name change, applications importing both jcsp.lang.* and java.util.* (or javax.swing*) would have to qualify declarations and constructions of "Timer" variables and objects - e.g: jcsp.lang.Timer tim = new jcsp.lang.Timer (); With this name change, even if both jcsp.lang.* and java.util.* are imported, we may declare JCSP timers without qualification - e.g: CSTimer tim = new CSTimer tim (); Note that the JDK1.3 java.util.Timer is a very different class from CSTimer. Warning: the old jcsp.lang.Timer has been deleted from this release - not deprecated. If it had just been deprecated, importing java.util.* would still require full qualification for references to its Timers. This means existing JCSP applications using JCSP timers will have to change all occurrences of "Timer" to "CSTimer" - many apologies. Aside: avoidance of a name clash was the reason why JCSP has the "CSProcess" interface, rather than just "Process". There has always been a "Process" class defined in java.lang (again with a very different purpose from ours). o Some improvements to various items in the documentation. o Re-packaging of the release as a single JAR file. o A new applet/application demo - Fireworks! Peter Welch. (11th. August, 2000) Changes since JCSP 0.95 release ------------------------------- o Change of name of the "Many2..." and "...2Many" channel classes. These have been changed to "Any2..." and "...2Any" channels. The "Any" names better reflect the semantics of these channels. ["Many" implied some kind of broadcast - which is not what these channels do.] This has been an outstanding request for some time. The old class names have not simply been deprecated - they have been deleted! The jcsp.lang section of the library would have become embarassingly top heavy with deprecated classes if they had been retained. Apologies to those who may need to make a lot of edits. I have a simple Unix cshell script that will make these edits to all .java files in, or below, a named directory. Please mail me (P.H.Welch@ukc.ac.uk) if you need it! o The bucket synchronisation primitive; o Generation of a jcsp.lang.ProcessInterruptedError if any process, blocked on a JCSP synchonisation primitive, is interrupted. This is not allowed (and is always a panic-induced design error). The error does not need to be caught (and, indeed, should *not* be caught) with a try-catch clutter surrounding the JCSP synchonisation. o Minor tweaks to the documentation (as ever). Peter Welch. (3rd. November, 1999) Changes since JCSP 0.94 release ------------------------------- o Links to Sun's JDK1.2 documentation (from the JCSP documentation) are now in place; o Minor tightening up of the ChannelAccept interface (for CALL channels) to enable the compiler to trap erroneous accepts - no effect on correct programs; o Minor tweaks to the documentation. Peter Welch. (28th. October, 1999) Changes since JCSP 0.5 release ------------------------------ o A more flexible API for ALTing; o Numerous new facilities (and some deprecated old ones); o More and better (javadoc)umentation - including several mini-tutorials. JCSP documentation is now produced using the JDK 1.2 javadoc tool; o More demonstration applications and applets; o (occam3) CALL channels; o Barrier and CREW synchronisation primitives; o Various pieces of maintenance. A source release will be made available shortly under either the GPL or Artistic open source licences. Please contact me (P.H.Welch@ukc.ac.uk). I *hope* to freeze this into a JCSP 1.0 release *shortly* and update the JCSP web pages suitably - at present, these offer only JCSP 0.5. Peter Welch. (28th. October, 1999)