Changes between Version 43 and Version 44 of DataParallel/VectPragma

Timestamp:

08/19/12 19:48:09 (10 months ago)

Author:

chak

Comment:

--

DataParallel/VectPragma

@@ -49 +49 @@
 The type constructor `T` must be in scope, but it may be imported.  'PData' and 'PRepr' instances are automatically generated by the vectoriser.
 
-Examples are the vectorisation of types, such as `Ordering` and `[]`, defined in the `Prelude`.
+Examples are the vectorisation of types, such as `Maybe` and `[]`, defined in the `Prelude`.
 
 === With right-hand side ===
@@ -57 +57 @@
 {-# VECTORISE type T = T' #-}
 }}}
-directs the vectoriser to replace `T` by `T'` in vectorised code and to use the corresponding data constructors of `T'` instead of those of `T`.  This implies that the two type constructors must be of the same kind and that the data constructors of `T` and `T'` need to be of the same number and type. 
+directs the vectoriser to replace `T` by `T'` in vectorised code. Vectorisation of `T` is abstract in that constructors of `T` may not occur in vectorised code. 
 
 The type constructor `T` must be in scope, but it may be imported.  'PData' and 'PRepr' instances must be explicitly defined — they are not automatically generated.
 
-An example is the handling of `Bool`, where we represent `Bool` by itself in vectorised code, but want to use the custom instances of 'PData' and 'PRepr' defined in the DPH libraries.
+An example is the vectorisation of parallel arrays, where `[::]` is replaced by `PArray` during vectorisation, but the vectoriser never looks at the representation of `[::]`.
 
 == The VECTORISE SCALAR pragma for type constructors ==
+
+All types imported from modules that have not been vectorised are regarded to be scalar types, and they can be used in encapsulated scalar code. If custom instances for the `PData` and `PRepr` classes are provided, these types can also be used in vectorisation code. The types represent themselves (as they are scalar) and are abstract; i.e., there constructors cannot be used in vectorised code. An example is the treatment of `Int`.  `Int`s can be used in vectorised code and remain unchanged by vectorisation.  However, the representation of `Int` by the `I#` data constructor wrapping an `Int#` is not exposed in vectorised code.  Instead, computations involving the representation need to be confined to scalar code.
 
 === Without right-hand side ===
@@ -71 +73 @@
 {-# VECTORISE SCALAR type T #-}
 }}}
-indicates that the type is scalar; i.e., it has no embedded arrays and its constructors can '''only''' be used in scalar code.  This is the default for all data types imported from non-vectorised modules.
+indicates that the type `T` is scalar; i.e., it cannot have any embedded arrays. Hence, the `T` represents itself in vectorised code. (No special vectorised version needs to be generated.)
 
-`T` that may be used in vectorised code, where `T` represents itself.  However, the representation of `T` is opaque in vectorised code. An example is the treatment of `Int`.  `Int`s can be used in vectorised code and remain unchanged by vectorisation.  However, the representation of `Int` by the `I#` data constructor wrapping an `Int#` is not exposed in vectorised code.  Instead, computations involving the representation need to be confined to scalar code.
+The type constructor `T` must be in scope, but it may be imported.  `PData` and `PRepr` instances for `T` need to be manually defined if needed at all.  (This is the fundamental difference to types for which the vectoriser determines automatically that they don't need a vectorised version: for the latter, the vectoriser automatically generates instances for `PData` and `PRepr`.)
 
-The type constructor `T` must be in scope, but it may be imported.  `PData` and `PRepr` instances for `T` need to be manually defined if needed at all.  (For types that the vectoriser automatically determines that they don't need a vectorised version, instances for `PData` and `PRepr` are still generated automatically.)
-
-NB: The crucial difference between `{-# VECTORISE SCALAR type T1 #-}` and `{-# VECTORISE type T2 #-}`, where `T2` embeds no parallel arrays, is that the *representation* (i.e., the constructors) of the former can only be used in scalar code. However, neither the representation of `T1` nor `T2` does get vectorised — so, both types are suitable for code that does not get vectorised due to vectorisation avoidance.
-
+An example is the handling of `Bool`, which is scalar and represents itself in vectorised code, but we want to use the custom instances of 'PData' and 'PRepr' defined in the DPH libraries.
 
 === With right-hand side ===
@@ -86 +85 @@
 {-# VECTORISE SCALAR type T = T' #-}
 }}}
-directs the vectoriser to replace `T` by `T'` in vectorised code, but its constructors can '''only''' be used in scalar code.
+directs the vectoriser to replace `T` by `T'` in vectorised code, but the type is abstract — i.e., its constructors cannot be used in vectorised code. Although, the representation of the types changes during vectorisation, it is still regarded as scalar, and hence, can be used in encapsulated scalar code.
 
 The type constructor `T` must be in scope, but it may be imported.  The `PData` and `PRepr` instances for `T` need to be manually defined. 
 
-An example is the handling of `[::]`, which the vectoriser maps to `PArray`, but it never looks at the implementation of `[::]`.
-
-'''TODO:'''
- * Maybe `VECTORISE ABSTRACT` would be a better name as it doesn't guarantee that the type constructor can be used in scalar code that doesn't need to be vectorised. It just means that the data constructors can '''only''' be used in scalar code — i.e., the vectoriser treats it as an abstract type.
+An example is the handling of `(->)`, which the vectoriser maps to `(:->)`, but it never looks at the implementation of `(->)` and allows its use in encapsulated scalar code.
 
 == The NOVECTORISE pragma for types ==