Skip to content

Commit

Permalink
More review comments
Browse files Browse the repository at this point in the history
  • Loading branch information
@agasser
agasser committed Nov 17, 2023
1 parent dfbc91b commit 4d948d1
Show file tree
Hide file tree
Showing 2 changed files with 15 additions and 51 deletions.
14 changes: 6 additions & 8 deletions source/docs/software/basic-programming/java-gc.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,27 +7,25 @@ Java garbage collection is an automatic process, which means that the programmer
Object Creation
---------------

Creating a large number of small objects in Java can lead to memory and performance issues. While the Java Garbage Collector (GC) is designed to handle memory management efficiently, creating too many small objects can overwhelm the GC and cause performance degradation.
Creating a large number of objects in Java can lead to memory and performance issues. While the Java Garbage Collector (GC) is designed to handle memory management efficiently, creating too many objects can overwhelm the GC and cause performance degradation.

Memory Concerns
^^^^^^^^^^^^^^^

When a large number of small objects are created, it increases the overall memory footprint of the application. This is because each object has its own overhead. While the overhead for a single object may be insignificant, it can become substantial when multiplied by a large number of objects.

The GC's job is to periodically identify and reclaim unused objects in memory. However, when the GC has to collect a large number of small objects frequently, it can become a performance bottleneck. This is because the GC has to perform more work to collect and process each object, which can slow down overall application performance.
When a large number of objects are created, it increases the overall memory footprint of the application. While the overhead for a single object may be insignificant, it can become substantial when multiplied by a large number of objects.

Performance Concerns
^^^^^^^^^^^^^^^^^^^^

The performance impact of creating a lot of small objects is not limited to GC overhead. Creating and destroying objects also involves CPU cycles, which can further impact application performance. Additionally, accessing and manipulating large numbers of small objects can lead to cache misses, which can further slow down the application.
The GC's job is to periodically identify and reclaim unused objects in memory. While garbage collection is running on an FRC robot coded in Java, execution of the robot program is paused. When the GC has to collect a large number of objects, it has to pause the application to run more frequently or for longer periods of time. This is because the GC has to perform more work to collect and process each object.

GC-related performance degradation in robot programs can manifest as occasional pauses, freezes, or loop overruns as the GC works to reclaim memory.

Design Considerations
^^^^^^^^^^^^^^^^^^^^^

If you anticipate your application creating a large number of small objects, it is important to consider design strategies to mitigate the potential memory and performance issues. Here are some strategies to consider:
If you anticipate your application creating a large number of short-lived objects, it is important to consider design strategies to mitigate the potential memory and performance issues. Here are some strategies to consider:

- Minimize object creation: Carefully evaluate the need for each object creation. If possible, reuse existing objects or use alternative data structures, such as arrays or primitives, to avoid creating new objects.

- Efficient data structures: Use data structures that are well-suited for the type of data you are working with. For example, if you are dealing with a large number of primitive values, consider using arrays or collections specifically designed for primitives.

In general, it is advisable to avoid creating a large number of small objects in Java unless it is necessary for the application's functionality. By carefully considering design strategies and optimizing object creation, you can minimize the memory and performance impact of creating small objects.
52 changes: 9 additions & 43 deletions source/docs/software/basic-programming/java-units.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,47 +28,13 @@ These concepts are used within the Units Library. For example, the **measure** *
Using the Units Library
-----------------------

The Java units library is available in the ``edu.wpi.first.units`` package. The most relevant classes are `edu.wpi.first.units.Units <https://github.wpilib.org/allwpilib/docs/beta/java/edu/wpi/first/units/Units.html>`__, which contains a set of predefined units; and `edu.wpi.first.units.Measure <https://github.wpilib.org/allwpilib/docs/beta/java/edu/wpi/first/units/Measure.html>`__, which is used to tag a value with a unit. It is recommended to static import ``edu.wpi.first.units.Units.*`` to get full access to all the predefined units.

The library comes with many predefined units:

+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+
| Type | Units |
+========================================================+========================================================================================================================+
| ``Measure<Distance>`` | ``Meters``, ``Millimeters``, ``Centimeters``, ``Inches``, ``Feet`` |
+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+
| ``Measure<Time>`` | ``Seconds``, ``Second``, ``Milliseconds``, ``Millisecond``, ``Microseconds``, ``Microsecond``, ``Minutes``, ``Minute`` |
+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+
| ``Measure<Angle>`` | ``Revolutions``, ``Rotations``, ``Radians``, ``Degrees`` |
+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+
| ``Measure<Velocity<Distance>>`` | ``MetersPerSecond``, ``FeetPerSecond``, ``InchesPerSecond`` |
+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+
| ``Measure<Velocity<Angle>>`` | ``RevolutionsPerSecond``, ``RotationsPerSecond``, ``RPM``, ``RadiansPerSecond``, ``DegreesPerSecond`` |
+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+
| ``Measure<Velocity<Velocity<Distance>>>`` | ``MetersPerSecondPerSecond``, ``Gs`` |
+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+
| ``Measure<Mass>`` | ``Kilograms``, ``Grams``, ``Pounds``, ``Ounces`` |
+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+
| ``Measure<Dimensionless>`` | ``Value``, ``Percent`` |
+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+
| ``Measure<Voltage>`` | ``Volts``, ``Millivolts`` |
+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+
| ``Measure<Current>`` | ``Amps``, ``Milliamps`` |
+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+
| ``Measure<Energy>`` | ``Joules``, ``Millijoules``, ``Kilojoules`` |
+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+
| ``Measure<Power>`` | ``Watts``, ``Milliwatts``, ``Horsepower`` |
+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+
| ``Measure<Temperature>`` | ``Kelvin``, ``Celsius``, ``Fahrenheit`` |
+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+
| ``Measure<Per<Voltage, Velocity<Distance>>>`` | ``VoltsPerMeterPerSecond`` |
+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+
| ``Measure<Per<Voltage, Velocity<Velocity<Distance>>>>``| ``VoltsPerMeterPerSecondSquared`` |
+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+
| ``Measure<Per<Voltage, Velocity<Angle>>>`` | ``VoltsPerRadianPerSecond`` |
+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+
| ``Measure<Per<Voltage, Velocity<Velocity<Angle>>>>`` | ``VoltsPerRadianPerSecondSquared`` |
+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+
The Java units library is available in the ``edu.wpi.first.units`` package. The most relevant classes are:

- The various classes for predefined dimensions, such as `Distance <https://github.wpilib.org/allwpilib/docs/beta/java/edu/wpi/first/units/Distance.html>`__ and `Time <https://github.wpilib.org/allwpilib/docs/beta/java/edu/wpi/first/units/Time.html>`__
- `Units <https://github.wpilib.org/allwpilib/docs/beta/java/edu/wpi/first/units/Units.html>`__, which contains a set of predefined units. Take a look a the `Units javadoc <https://github.wpilib.org/allwpilib/docs/beta/java/edu/wpi/first/units/Units.html>`__ to browse the available units and their types.
- `Measure <https://github.wpilib.org/allwpilib/docs/beta/java/edu/wpi/first/units/Measure.html>`__, which is used to tag a value with a unit.

.. note:: It is recommended to static import ``edu.wpi.first.units.Units.*`` to get full access to all the predefined units.

Java Generics
^^^^^^^^^^^^^
Expand Down Expand Up @@ -327,8 +293,8 @@ There are four ways to define a new unit that isn't already present in the libra

- Using the ``Unit.per`` or ``Unit.mult`` methods to create a composite of two other units;
- Using the ``Milli``, ``Micro``, and ``Kilo`` helper methods;
- Using the ``derive`` method and customizing how the new unit relates to the base unit;
- Subclassing ``Unit`` to define a new diimension
- Using the ``derive`` method and customizing how the new unit relates to the base unit; and
- Subclassing ``Unit`` to define a new dimension.

New units can be defined as combinations of existing units using the ``Unit.mult`` and ``Unit.per`` methods.

Expand Down

0 comments on commit 4d948d1

Please sign in to comment.