Split Limited Types module into chapters

courses/fundamentals_of_ada/120_limited_types/01-introduction.rst

@@ -0,0 +1,76 @@
+==============
+Introduction
+==============
+
+-------
+Views
+-------
+
+* Specify how values and objects may be manipulated
+* Are implicit in much of the language semantics
+
+   - Constants are just variables without any assignment view
+   - Task types, protected types implicitly disallow assignment
+   - Mode :ada:`in` formal parameters disallow assignment
+
+.. code:: Ada
+
+   Variable : Integer := 0;
+   ...
+   -- P's view of X prevents modification
+   procedure P(X :  in  Integer) is
+   begin
+       ...
+   end P;
+   ...
+   P(Variable);
+
+-------------------------------
+Limited Type Views' Semantics
+-------------------------------
+
+* Prevents copying via predefined assignment
+
+   - Disallows assignment between objects
+   - Must make your own `copy` procedure if needed
+
+   .. code:: Ada
+
+      type File is limited ...
+      ...
+      F1, F2 : File;
+      ...
+      F1 := F2; -- compile error
+
+* Prevents incorrect comparison semantics
+
+   - Disallows predefined equality operator
+   - Make your own equality function `=` if needed
+
+-------------------------------
+Inappropriate Copying Example
+-------------------------------
+
+.. code:: Ada
+
+   type File is ...
+   F1, F2 : File;
+   ...
+   Open (F1);
+   Write (F1, "Hello");
+   -- What is this assignment really trying to do?
+   F2 := F1;
+
+-----------------------------
+Intended Effects of Copying
+-----------------------------
+
+.. code:: Ada
+
+   type File is ...
+   F1, F2 : File;
+   ...
+   Open (F1);
+   Write (F1, "Hello");
+   Copy (Source => F1, Target => F2);
+

courses/fundamentals_of_ada/120_limited_types/02-declarations.rst

@@ -0,0 +1,149 @@
+==============
+Declarations
+==============
+
+---------------------------
+Limited Type Declarations
+---------------------------
+
+* Syntax
+
+   - Additional keyword limited added to record type declaration
+
+   .. code:: Ada
+
+      type defining_identifier is limited record
+          component_list
+      end record;
+
+* Are always record types unless also private
+
+   - More in a moment...
+
+---------------------------
+Approximate Analog in C++
+---------------------------
+
+.. code:: C++
+
+   class Stack {
+   public:
+     Stack ();
+     void Push (int X);
+     void Pop (int& X);
+     ...
+   private:
+     ...
+     // assignment operator hidden
+     Stack& operator= (const Stack& other);
+   }; // Stack
+
+-------------------
+Spin Lock Example
+-------------------
+
+.. code:: Ada
+
+   with Interfaces;
+   package Multiprocessor_Mutex is
+     -- prevent copying of a lock
+     type Spin_Lock is limited record
+       Flag : Interfaces.Unsigned_8;
+     end record;
+     procedure Lock  (This : in out Spin_Lock);
+     procedure Unlock  (This : in out Spin_Lock);
+     pragma Inline (Lock, Unlock);
+   end Multiprocessor_Mutex;
+
+-----------------------------
+Parameter Passing Mechanism
+-----------------------------
+
+* Always "by-reference" if explicitly limited
+
+   - Necessary for various reasons (:ada:`task` and :ada:`protected` types, etc)
+   - Advantageous when required for proper behavior
+
+* By definition, these subprograms would be called concurrently
+
+   - Cannot operate on copies of parameters!
+
+.. code:: Ada
+
+   procedure Lock  (This : in out Spin_Lock);
+   procedure Unlock (This : in out Spin_Lock);
+
+-------------------------------------
+Composites with Limited Types
+-------------------------------------
+
+* Composite containing a limited type becomes limited as well
+
+   * Example: Array of limited elements
+
+      - Array becomes a limited type
+
+   * Prevents assignment and equality loop-holes
+
+.. code:: Ada
+
+   declare
+     -- if we can't copy component S, we can't copy User_Type
+     type User_Type is record -- limited because S is limited
+       S : File;
+       ...
+     end record;
+     A, B : User_Type;
+   begin
+     A := B;  -- not legal since limited
+     ...
+   end;
+
+------
+Quiz
+------
+
+.. include:: ../quiz/limited_syntax/quiz.rst
+
+------
+Quiz
+------
+
+.. include:: ../quiz/limited_operators/quiz.rst
+..
+------
+Quiz
+------
+
+.. code:: Ada
+
+   package P is
+      type T is limited null record;
+      type R is record
+         F1 : Integer;
+         F2 : T;
+      end record;
+   end P;
+
+   with P;
+   procedure Main is
+      T1, T2 : P.T;
+      R1, R2 : P.R;
+   begin
+
+Which assignment(s) is (are) legal?
+
+   A. ``T1    := T2;``
+   B. ``R1    := R2;``
+   C. :answermono:`R1.F1 := R2.F1;`
+   D. ``R2.F2 := R2.F2;``
+
+.. container:: animate
+
+   Explanations
+
+   A. :ada:`T1` and :ada:`T2` are :ada:`limited types`
+   B. :ada:`R1` and :ada:`R2` contain :ada:`limited` types so they are also :ada:`limited`
+   C. Theses components are not :ada:`limited` types
+   D. These components are of a :ada:`limited` type
+

courses/fundamentals_of_ada/120_limited_types/03-creating_values.rst

@@ -0,0 +1,132 @@
+=================
+Creating Values
+=================
+
+-----------------
+Creating Values
+-----------------
+
+* Initialization is not assignment (but looks like it)!
+* Via **limited constructor functions**
+
+   - Functions returning values of limited types
+
+* Via an **aggregate**
+
+    - :dfn:`limited aggregate` when used for a :ada:`limited` type
+
+.. code:: Ada
+
+   type Spin_Lock is limited record
+     Flag : Interfaces.Unsigned_8;
+   end record;
+   ...
+   Mutex : Spin_Lock := (Flag => 0); -- limited aggregate
+
+-------------------------------
+Limited Constructor Functions
+-------------------------------
+
+.. container:: columns
+
+ .. container:: column
+
+    * Allowed wherever limited aggregates are allowed
+    * More capable (can perform arbitrary computations)
+    * Necessary when limited type is also private
+
+       - Users won't have visibility required to express aggregate contents
+
+ .. container:: column
+
+    .. code:: Ada
+
+       function F return Spin_Lock
+       is
+       begin
+         ...
+         return (Flag => 0);
+       end F;
+
+---------------------------------------
+Writing Limited Constructor Functions
+---------------------------------------
+
+* Remember - copying is not allowed
+
+.. code:: Ada
+
+   function F return Spin_Lock is
+     Local_X : Spin_Lock;
+   begin
+     ...
+     return Local_X; -- this is a copy - not legal
+      -- (also illegal because of pass-by-reference)
+   end F;
+
+.. code:: Ada
+
+   Global_X : Spin_Lock;
+   function F return Spin_Lock is
+   begin
+     ...
+     -- This is not legal staring with Ada2005
+     return Global_X; -- this is a copy
+   end F;
+
+-------------------
+ "Built In-Place"
+-------------------
+
+* Limited aggregates and functions, specifically
+* No copying done by implementation
+
+   - Values are constructed in situ
+
+.. code:: Ada
+
+   Mutex : Spin_Lock := (Flag => 0);
+
+.. code:: Ada
+
+   function F return Spin_Lock is
+   begin
+     return (Flag => 0);
+   end F;
+
+------
+Quiz
+------
+
+.. include:: ../quiz/limited_constructor_syntax/quiz.rst
+
+------
+Quiz
+------
+
+.. code:: Ada
+
+   package P is
+      type T is limited record
+         F1 : Integer;
+         F2 : Character;
+      end record;
+      Zero : T := (0, ' ');
+      One : constant T := (1, 'a');
+      Two : T;
+      function F return T;
+   end P;
+
+Which is a correct completion of F?
+
+A. :answermono:`return (3, 'c');`
+B. | ``Two := (2, 'b');``
+   | ``return Two;``
+C. ``return One;``
+D. ``return Zero;``
+
+.. container:: animate
+
+   :ada:`A` contains an "in-place" return. The rest all rely on
+   other objects, which would require an (illegal) copy.
+