annotate scripts/java/javamem.m @ 27918:b442ec6dda5c

use centralized file for copyright info for individual contributors * COPYRIGHT.md: New file. * In most other files, use "Copyright (C) YYYY-YYYY The Octave Project Developers" instead of tracking individual names in separate source files. The motivation is to reduce the effort required to update the notices each year. Until now, the Octave source files contained copyright notices that list individual contributors. I adopted these file-scope copyright notices because that is what everyone was doing 30 years ago in the days before distributed version control systems. But now, with many contributors and modern version control systems, having these file-scope copyright notices causes trouble when we update copyright years or refactor code. Over time, the file-scope copyright notices may become outdated as new contributions are made or code is moved from one file to another. Sometimes people contribute significant patches but do not add a line claiming copyright. Other times, people add a copyright notice for their contribution but then a later refactoring moves part or all of their contribution to another file and the notice is not moved with the code. As a practical matter, moving such notices is difficult -- determining what parts are due to a particular contributor requires a time-consuming search through the project history. Even managing the yearly update of copyright years is problematic. We have some contributors who are no longer living. Should we update the copyright dates for their contributions when we release new versions? Probably not, but we do still want to claim copyright for the project as a whole. To minimize the difficulty of maintaining the copyright notices, I would like to change Octave's sources to use what is described here: https://softwarefreedom.org/resources/2012/ManagingCopyrightInformation.html in the section "Maintaining centralized copyright notices": The centralized notice approach consolidates all copyright notices in a single location, usually a top-level file. This file should contain all of the copyright notices provided project contributors, unless the contribution was clearly insignificant. It may also credit -- without a copyright notice -- anyone who helped with the project but did not contribute code or other copyrighted material. This approach captures less information about contributions within individual files, recognizing that the DVCS is better equipped to record those details. As we mentioned before, it does have one disadvantage as compared to the file-scope approach: if a single file is separated from the distribution, the recipient won't see the contributors' copyright notices. But this can be easily remedied by including a single copyright notice in each file's header, pointing to the top-level file: Copyright YYYY-YYYY The Octave Project Developers See the COPYRIGHT file at the top-level directory of this distribution or at https://octave.org/COPYRIGHT.html. followed by the usual GPL copyright statement. For more background, see the discussion here: https://lists.gnu.org/archive/html/octave-maintainers/2020-01/msg00009.html Most files in the following directories have been skipped intentinally in this changeset: doc libgui/qterminal liboctave/external m4
author John W. Eaton <jwe@octave.org>
date Mon, 06 Jan 2020 15:38:17 -0500
parents 00f796120a6d
children 1891570abac8
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
27918
b442ec6dda5c use centralized file for copyright info for individual contributors
John W. Eaton <jwe@octave.org>
parents: 26376
diff changeset
1 ## Copyright (C) 2010-2019 The Octave Project Developers
b442ec6dda5c use centralized file for copyright info for individual contributors
John W. Eaton <jwe@octave.org>
parents: 26376
diff changeset
2 ##
b442ec6dda5c use centralized file for copyright info for individual contributors
John W. Eaton <jwe@octave.org>
parents: 26376
diff changeset
3 ## See the file COPYRIGHT.md in the top-level directory of this distribution
b442ec6dda5c use centralized file for copyright info for individual contributors
John W. Eaton <jwe@octave.org>
parents: 26376
diff changeset
4 ## or <https://octave.org/COPYRIGHT.html/>.
b442ec6dda5c use centralized file for copyright info for individual contributors
John W. Eaton <jwe@octave.org>
parents: 26376
diff changeset
5 ##
19593
446c46af4b42 strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents: 17744
diff changeset
6 ##
15746
da26f72408a7 update copyright statements in newly added java files
John W. Eaton <jwe@octave.org>
parents: 15625
diff changeset
7 ## This file is part of Octave.
da26f72408a7 update copyright statements in newly added java files
John W. Eaton <jwe@octave.org>
parents: 15625
diff changeset
8 ##
24534
194eb4bd202b maint: Update punctuation for GPL v3 license text.
Rik <rik@octave.org>
parents: 23220
diff changeset
9 ## Octave is free software: you can redistribute it and/or modify it
15746
da26f72408a7 update copyright statements in newly added java files
John W. Eaton <jwe@octave.org>
parents: 15625
diff changeset
10 ## under the terms of the GNU General Public License as published by
24534
194eb4bd202b maint: Update punctuation for GPL v3 license text.
Rik <rik@octave.org>
parents: 23220
diff changeset
11 ## the Free Software Foundation, either version 3 of the License, or
22755
3a2b891d0b33 maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents: 22323
diff changeset
12 ## (at your option) any later version.
15746
da26f72408a7 update copyright statements in newly added java files
John W. Eaton <jwe@octave.org>
parents: 15625
diff changeset
13 ##
da26f72408a7 update copyright statements in newly added java files
John W. Eaton <jwe@octave.org>
parents: 15625
diff changeset
14 ## Octave is distributed in the hope that it will be useful, but
da26f72408a7 update copyright statements in newly added java files
John W. Eaton <jwe@octave.org>
parents: 15625
diff changeset
15 ## WITHOUT ANY WARRANTY; without even the implied warranty of
22755
3a2b891d0b33 maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents: 22323
diff changeset
16 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
3a2b891d0b33 maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents: 22323
diff changeset
17 ## GNU General Public License for more details.
15746
da26f72408a7 update copyright statements in newly added java files
John W. Eaton <jwe@octave.org>
parents: 15625
diff changeset
18 ##
15625
acf0addfc610 include Octave Forge java package in core Octave
John W. Eaton <jwe@octave.org>
parents:
diff changeset
19 ## You should have received a copy of the GNU General Public License
acf0addfc610 include Octave Forge java package in core Octave
John W. Eaton <jwe@octave.org>
parents:
diff changeset
20 ## along with Octave; see the file COPYING. If not, see
24534
194eb4bd202b maint: Update punctuation for GPL v3 license text.
Rik <rik@octave.org>
parents: 23220
diff changeset
21 ## <https://www.gnu.org/licenses/>.
15625
acf0addfc610 include Octave Forge java package in core Octave
John W. Eaton <jwe@octave.org>
parents:
diff changeset
22
acf0addfc610 include Octave Forge java package in core Octave
John W. Eaton <jwe@octave.org>
parents:
diff changeset
23 ## -*- texinfo -*-
20852
516bb87ea72e 2015 Code Sprint: remove class of function from docstring for all m-files.
Rik <rik@octave.org>
parents: 20181
diff changeset
24 ## @deftypefn {} {} javamem ()
516bb87ea72e 2015 Code Sprint: remove class of function from docstring for all m-files.
Rik <rik@octave.org>
parents: 20181
diff changeset
25 ## @deftypefnx {} {@var{jmem} =} javamem ()
20160
03b9d17a2d95 doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19596
diff changeset
26 ## Show the current memory usage of the Java virtual machine (JVM) and run the
03b9d17a2d95 doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19596
diff changeset
27 ## garbage collector.
15625
acf0addfc610 include Octave Forge java package in core Octave
John W. Eaton <jwe@octave.org>
parents:
diff changeset
28 ##
15772
0f1a143e5002 Overhaul scripts/java directory to conform to Octave core.
Rik <rik@octave.org>
parents: 15748
diff changeset
29 ## When no return argument is given the info is printed to the screen.
20160
03b9d17a2d95 doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19596
diff changeset
30 ## Otherwise, the output cell array @var{jmem} contains Maximum, Total, and
03b9d17a2d95 doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19596
diff changeset
31 ## Free memory (in bytes).
15625
acf0addfc610 include Octave Forge java package in core Octave
John W. Eaton <jwe@octave.org>
parents:
diff changeset
32 ##
20160
03b9d17a2d95 doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19596
diff changeset
33 ## All Java-based routines are run in the JVM's shared memory pool, a
03b9d17a2d95 doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19596
diff changeset
34 ## dedicated and separate part of memory claimed by the JVM from your
03b9d17a2d95 doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19596
diff changeset
35 ## computer's total memory (which comprises physical RAM and virtual memory /
03b9d17a2d95 doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19596
diff changeset
36 ## swap space on hard disk).
15625
acf0addfc610 include Octave Forge java package in core Octave
John W. Eaton <jwe@octave.org>
parents:
diff changeset
37 ##
16392
801297f14e4b doc: Improve documentation for Java chapter and java functions.
Rik <rik@octave.org>
parents: 15826
diff changeset
38 ## The maximum allowable memory usage can be configured using the file
20160
03b9d17a2d95 doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19596
diff changeset
39 ## @file{java.opts}. The directory where this file resides is determined by
03b9d17a2d95 doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19596
diff changeset
40 ## the environment variable @w{@env{OCTAVE_JAVA_DIR}}. If unset, the directory
03b9d17a2d95 doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19596
diff changeset
41 ## where @file{javaaddpath.m} resides is used instead (typically
18679
a142f35f3cb6 doc: Fix unbalanced parentheses in documentation.
Rik <rik@octave.org>
parents: 17744
diff changeset
42 ## @file{@w{@env{OCTAVE_HOME}}/share/octave/@w{@env{OCTAVE_VERSION}}/m/java/}).
15772
0f1a143e5002 Overhaul scripts/java directory to conform to Octave core.
Rik <rik@octave.org>
parents: 15748
diff changeset
43 ##
20160
03b9d17a2d95 doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19596
diff changeset
44 ## @file{java.opts} is a plain text file with one option per line. The default
03b9d17a2d95 doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19596
diff changeset
45 ## initial memory size and default maximum memory size (which are both system
03b9d17a2d95 doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19596
diff changeset
46 ## dependent) can be overridden like so:
15772
0f1a143e5002 Overhaul scripts/java directory to conform to Octave core.
Rik <rik@octave.org>
parents: 15748
diff changeset
47 ##
0f1a143e5002 Overhaul scripts/java directory to conform to Octave core.
Rik <rik@octave.org>
parents: 15748
diff changeset
48 ## @nospell{-Xms64m}
0f1a143e5002 Overhaul scripts/java directory to conform to Octave core.
Rik <rik@octave.org>
parents: 15748
diff changeset
49 ##
0f1a143e5002 Overhaul scripts/java directory to conform to Octave core.
Rik <rik@octave.org>
parents: 15748
diff changeset
50 ## @nospell{-Xmx512m}
0f1a143e5002 Overhaul scripts/java directory to conform to Octave core.
Rik <rik@octave.org>
parents: 15748
diff changeset
51 ##
16392
801297f14e4b doc: Improve documentation for Java chapter and java functions.
Rik <rik@octave.org>
parents: 15826
diff changeset
52 ## (in megabytes in this example).
20160
03b9d17a2d95 doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19596
diff changeset
53 ## You can adapt these values to your own requirements if your system has
03b9d17a2d95 doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19596
diff changeset
54 ## limited available physical memory or if you get Java memory errors.
15625
acf0addfc610 include Octave Forge java package in core Octave
John W. Eaton <jwe@octave.org>
parents:
diff changeset
55 ##
20160
03b9d17a2d95 doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19596
diff changeset
56 ## @qcode{"Total memory"} is what the operating system has currently assigned
20181
aa36fb998a4d maint: Remove unnecessary whitespace at end of lines.
Rik <rik@octave.org>
parents: 20160
diff changeset
57 ## to the JVM and depends on actual and active memory usage.
20160
03b9d17a2d95 doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19596
diff changeset
58 ## @qcode{"Free memory"} is self-explanatory. During operation of Java-based
03b9d17a2d95 doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19596
diff changeset
59 ## Octave functions the amount of Total and Free memory will vary, due to
03b9d17a2d95 doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19596
diff changeset
60 ## Java's own cleaning up and your operating system's memory management.
15625
acf0addfc610 include Octave Forge java package in core Octave
John W. Eaton <jwe@octave.org>
parents:
diff changeset
61 ## @end deftypefn
acf0addfc610 include Octave Forge java package in core Octave
John W. Eaton <jwe@octave.org>
parents:
diff changeset
62
acf0addfc610 include Octave Forge java package in core Octave
John W. Eaton <jwe@octave.org>
parents:
diff changeset
63 ## Author: Philip Nienhuis
acf0addfc610 include Octave Forge java package in core Octave
John W. Eaton <jwe@octave.org>
parents:
diff changeset
64 ## Created: 2010-03-25
19593
446c46af4b42 strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents: 17744
diff changeset
65 ## Updates:
15625
acf0addfc610 include Octave Forge java package in core Octave
John W. Eaton <jwe@octave.org>
parents:
diff changeset
66 ## 2010-03-26 Changed name to javamem & indentation to double spaces
acf0addfc610 include Octave Forge java package in core Octave
John W. Eaton <jwe@octave.org>
parents:
diff changeset
67 ## 2010-08-25 Corrected text on java memory assignments
acf0addfc610 include Octave Forge java package in core Octave
John W. Eaton <jwe@octave.org>
parents:
diff changeset
68 ## 2010-09-05 Further overhauled help text
acf0addfc610 include Octave Forge java package in core Octave
John W. Eaton <jwe@octave.org>
parents:
diff changeset
69
15772
0f1a143e5002 Overhaul scripts/java directory to conform to Octave core.
Rik <rik@octave.org>
parents: 15748
diff changeset
70 function jmem = javamem ()
15625
acf0addfc610 include Octave Forge java package in core Octave
John W. Eaton <jwe@octave.org>
parents:
diff changeset
71
15790
921912c92102 Deprecate java_invoke, replace with javaMethod.
Rik <rik@octave.org>
parents: 15772
diff changeset
72 rt = javaMethod ("getRuntime", "java.lang.Runtime");
15625
acf0addfc610 include Octave Forge java package in core Octave
John W. Eaton <jwe@octave.org>
parents:
diff changeset
73 rt.gc;
15772
0f1a143e5002 Overhaul scripts/java directory to conform to Octave core.
Rik <rik@octave.org>
parents: 15748
diff changeset
74 jvmem = cell (3, 1);
15826
93516992ee34 javamem.m: adapt to 'boxing' Java doubles
Philip Nienhuis <prnienhuis@users.sf.net>
parents: 15790
diff changeset
75 jvmem{1} = rt.maxMemory ();
93516992ee34 javamem.m: adapt to 'boxing' Java doubles
Philip Nienhuis <prnienhuis@users.sf.net>
parents: 15790
diff changeset
76 jvmem{2} = rt.totalMemory ();
93516992ee34 javamem.m: adapt to 'boxing' Java doubles
Philip Nienhuis <prnienhuis@users.sf.net>
parents: 15790
diff changeset
77 jvmem{3} = rt.freeMemory ();
15625
acf0addfc610 include Octave Forge java package in core Octave
John W. Eaton <jwe@octave.org>
parents:
diff changeset
78
15748
54e8c2527a9e style and doc fixes for newly imported Java package .m files
John W. Eaton <jwe@octave.org>
parents: 15746
diff changeset
79 if (nargout == 0)
21634
96518f623c91 Backed out changeset dcf8922b724b
Mike Miller <mtmiller@octave.org>
parents: 21633
diff changeset
80 printf ("\nJava virtual machine (JVM) memory info:\n");
96518f623c91 Backed out changeset dcf8922b724b
Mike Miller <mtmiller@octave.org>
parents: 21633
diff changeset
81 printf ("Maximum available memory: %5d MiB;\n",
15772
0f1a143e5002 Overhaul scripts/java directory to conform to Octave core.
Rik <rik@octave.org>
parents: 15748
diff changeset
82 jvmem{1} / 1024 / 1024);
21634
96518f623c91 Backed out changeset dcf8922b724b
Mike Miller <mtmiller@octave.org>
parents: 21633
diff changeset
83 printf (" (...running garbage collector...)\n");
96518f623c91 Backed out changeset dcf8922b724b
Mike Miller <mtmiller@octave.org>
parents: 21633
diff changeset
84 printf ("OK, current status:\n");
96518f623c91 Backed out changeset dcf8922b724b
Mike Miller <mtmiller@octave.org>
parents: 21633
diff changeset
85 printf ("Total memory in virtual machine: %5d MiB;\n",
15772
0f1a143e5002 Overhaul scripts/java directory to conform to Octave core.
Rik <rik@octave.org>
parents: 15748
diff changeset
86 jvmem{2} / 1024 / 1024);
21634
96518f623c91 Backed out changeset dcf8922b724b
Mike Miller <mtmiller@octave.org>
parents: 21633
diff changeset
87 printf ("Free memory in virtual machine: %5d MiB;\n",
15772
0f1a143e5002 Overhaul scripts/java directory to conform to Octave core.
Rik <rik@octave.org>
parents: 15748
diff changeset
88 jvmem{3} / 1024 / 1024);
21634
96518f623c91 Backed out changeset dcf8922b724b
Mike Miller <mtmiller@octave.org>
parents: 21633
diff changeset
89 printf ("%d CPUs available.\n", rt.availableProcessors ());
15625
acf0addfc610 include Octave Forge java package in core Octave
John W. Eaton <jwe@octave.org>
parents:
diff changeset
90 else
15772
0f1a143e5002 Overhaul scripts/java directory to conform to Octave core.
Rik <rik@octave.org>
parents: 15748
diff changeset
91 jmem = jvmem;
15625
acf0addfc610 include Octave Forge java package in core Octave
John W. Eaton <jwe@octave.org>
parents:
diff changeset
92 endif
acf0addfc610 include Octave Forge java package in core Octave
John W. Eaton <jwe@octave.org>
parents:
diff changeset
93
acf0addfc610 include Octave Forge java package in core Octave
John W. Eaton <jwe@octave.org>
parents:
diff changeset
94 endfunction