1Float.ArrayLabels(3) OCaml library Float.ArrayLabels(3)
2
6 Float.ArrayLabels - Float arrays with packed representation (labeled
7 functions).
8
10 Module Float.ArrayLabels
11
13 Module ArrayLabels
14 : sig end
15 Float arrays with packed representation (labeled functions).
18 type t = floatarray
24 The type of float arrays with packed representation.
27 Since 4.08.0
30 val length : t -> int
34 Return the length (number of elements) of the given floatarray.
36 val get : t -> int -> float
40 get a n returns the element number n of floatarray a .
43 Raises Invalid_argument if n is outside the range 0 to (length a - 1) .
46 val set : t -> int -> float -> unit
50 set a n x modifies floatarray a in place, replacing element number n
53 with x .
54 Raises Invalid_argument if n is outside the range 0 to (length a - 1) .
57 val make : int -> float -> t
61 make n x returns a fresh floatarray of length n , initialized with x .
64 Raises Invalid_argument if n < 0 or n > Sys.max_floatarray_length .
67 val create : int -> t
71 create n returns a fresh floatarray of length n , with uninitialized
74 data.
75 Raises Invalid_argument if n < 0 or n > Sys.max_floatarray_length .
78 val init : int -> f:(int -> float) -> t
82 init n ~f returns a fresh floatarray of length n , with element number
85 i initialized to the result of f i . In other terms, init n ~f tabu‐
86 lates the results of f applied to the integers 0 to n-1 .
87 Raises Invalid_argument if n < 0 or n > Sys.max_floatarray_length .
90 val append : t -> t -> t
94 append v1 v2 returns a fresh floatarray containing the concatenation of
97 the floatarrays v1 and v2 .
98 Raises Invalid_argument if length v1 + length v2 > Sys.max_floatar‐
101 ray_length .
102 val concat : t list -> t
106 Same as Float.ArrayLabels.append , but concatenates a list of floatar‐
108 rays.
109 val sub : t -> pos:int -> len:int -> t
113 sub a ~pos ~len returns a fresh floatarray of length len , containing
116 the elements number pos to pos + len - 1 of floatarray a .
117 Raises Invalid_argument if pos and len do not designate a valid subar‐
120 ray of a ; that is, if pos < 0 , or len < 0 , or pos + len > length a .
121 val copy : t -> t
125 copy a returns a copy of a , that is, a fresh floatarray containing the
128 same elements as a .
129 val fill : t -> pos:int -> len:int -> float -> unit
133 fill a ~pos ~len x modifies the floatarray a in place, storing x in el‐
136 ements number pos to pos + len - 1 .
137 Raises Invalid_argument if pos and len do not designate a valid subar‐
140 ray of a .
141 val blit : src:t -> src_pos:int -> dst:t -> dst_pos:int -> len:int ->
145 unit
146 blit ~src ~src_pos ~dst ~dst_pos ~len copies len elements from floatar‐
149 ray src , starting at element number src_pos , to floatarray dst ,
150 starting at element number dst_pos . It works correctly even if src
151 and dst are the same floatarray, and the source and destination chunks
152 overlap.
153 Raises Invalid_argument if src_pos and len do not designate a valid
156 subarray of src , or if dst_pos and len do not designate a valid subar‐
157 ray of dst .
158 val to_list : t -> float list
162 to_list a returns the list of all the elements of a .
165 val of_list : float list -> t
169 of_list l returns a fresh floatarray containing the elements of l .
172 Raises Invalid_argument if the length of l is greater than
175 Sys.max_floatarray_length .
176 Iterators
181 val iter : f:(float -> unit) -> t -> unit
182 iter ~f a applies function f in turn to all the elements of a . It is
185 equivalent to f a.(0); f a.(1); ...; f a.(length a - 1); () .
186 val iteri : f:(int -> float -> unit) -> t -> unit
190 Same as Float.ArrayLabels.iter , but the function is applied with the
192 index of the element as first argument, and the element itself as sec‐
193 ond argument.
194 val map : f:(float -> float) -> t -> t
198 map ~f a applies function f to all the elements of a , and builds a
201 floatarray with the results returned by f .
202 val mapi : f:(int -> float -> float) -> t -> t
206 Same as Float.ArrayLabels.map , but the function is applied to the in‐
208 dex of the element as first argument, and the element itself as second
209 argument.
210 val fold_left : f:('a -> float -> 'a) -> init:'a -> t -> 'a
214 fold_left ~f x ~init computes f (... (f (f x init.(0)) init.(1)) ...)
217 init.(n-1) , where n is the length of the floatarray init .
218 val fold_right : f:(float -> 'a -> 'a) -> t -> init:'a -> 'a
222 fold_right f a init computes f a.(0) (f a.(1) ( ... (f a.(n-1) init)
225 ...)) , where n is the length of the floatarray a .
226 Iterators on two arrays
231 val iter2 : f:(float -> float -> unit) -> t -> t -> unit
232 Array.iter2 ~f a b applies function f to all the elements of a and b .
235 Raises Invalid_argument if the floatarrays are not the same size.
238 val map2 : f:(float -> float -> float) -> t -> t -> t
242 map2 ~f a b applies function f to all the elements of a and b , and
245 builds a floatarray with the results returned by f : [| f a.(0) b.(0);
246 ...; f a.(length a - 1) b.(length b - 1)|] .
247 Raises Invalid_argument if the floatarrays are not the same size.
250 Array scanning
255 val for_all : f:(float -> bool) -> t -> bool
256 for_all ~f [|a1; ...; an|] checks if all elements of the floatarray
259 satisfy the predicate f . That is, it returns (f a1) && (f a2) && ...
260 && (f an) .
261 val exists : f:(float -> bool) -> t -> bool
265 exists f [|a1; ...; an|] checks if at least one element of the floatar‐
268 ray satisfies the predicate f . That is, it returns (f a1) || (f a2) ||
269 ... || (f an) .
270 val mem : float -> set:t -> bool
274 mem a ~set is true if and only if there is an element of set that is
277 structurally equal to a , i.e. there is an x in set such that compare a
278 x = 0 .
279 val mem_ieee : float -> set:t -> bool
283 Same as Float.ArrayLabels.mem , but uses IEEE equality instead of
285 structural equality.
286 Sorting
291 val sort : cmp:(float -> float -> int) -> t -> unit
292 Sort a floatarray in increasing order according to a comparison func‐
294 tion. The comparison function must return 0 if its arguments compare
295 as equal, a positive integer if the first is greater, and a negative
296 integer if the first is smaller (see below for a complete specifica‐
297 tion). For example, compare is a suitable comparison function. After
298 calling sort , the array is sorted in place in increasing order. sort
299 is guaranteed to run in constant heap space and (at most) logarithmic
300 stack space.
301 The current implementation uses Heap Sort. It runs in constant stack
303 space.
304 Specification of the comparison function: Let a be the floatarray and
306 cmp the comparison function. The following must be true for all x , y ,
307 z in a :
308 - cmp x y > 0 if and only if cmp y x < 0
310 - if cmp x y >= 0 and cmp y z >= 0 then cmp x z >= 0
312 When sort returns, a contains the same elements as before, reordered in
314 such a way that for all i and j valid indices of a :
315 - cmp a.(i) a.(j) >= 0 if and only if i >= j
317 val stable_sort : cmp:(float -> float -> int) -> t -> unit
322 Same as Float.ArrayLabels.sort , but the sorting algorithm is stable
324 (i.e. elements that compare equal are kept in their original order)
325 and not guaranteed to run in constant heap space.
326 The current implementation uses Merge Sort. It uses a temporary
328 floatarray of length n/2 , where n is the length of the floatarray. It
329 is usually faster than the current implementation of Float.ArrayLa‐
330 bels.sort .
331 val fast_sort : cmp:(float -> float -> int) -> t -> unit
335 Same as Float.ArrayLabels.sort or Float.ArrayLabels.stable_sort ,
337 whichever is faster on typical input.
338 Float arrays and Sequences
343 val to_seq : t -> float Seq.t
344 Iterate on the floatarray, in increasing order. Modifications of the
346 floatarray during iteration will be reflected in the sequence.
347 val to_seqi : t -> (int * float) Seq.t
351 Iterate on the floatarray, in increasing order, yielding indices along
353 elements. Modifications of the floatarray during iteration will be re‐
354 flected in the sequence.
355 val of_seq : float Seq.t -> t
359 Create an array from the generator.
361 val map_to_array : f:(float -> 'a) -> t -> 'a array
365 map_to_array ~f a applies function f to all the elements of a , and
368 builds an array with the results returned by f : [| f a.(0); f a.(1);
369 ...; f a.(length a - 1) |] .
370 val map_from_array : f:('a -> float) -> 'a array -> t
374 map_from_array ~f a applies function f to all the elements of a , and
377 builds a floatarray with the results returned by f .
378 Arrays and concurrency safety
383 Care must be taken when concurrently accessing float arrays from multi‐
384 ple domains: accessing an array will never crash a program, but unsyn‐
385 chronized accesses might yield surprising (non-sequentially-consistent)
386 results.
387 Atomicity
390 Every float array operation that accesses more than one array element
391 is not atomic. This includes iteration, scanning, sorting, splitting
392 and combining arrays.
393 For example, consider the following program:
395 let size = 100_000_000
396 let a = Float.ArrayLabels.make size 1.
397 let update a f () =
398 Float.ArrayLabels.iteri ~f:(fun i x -> Float.Array.set a i (f x)) a
399 let d1 = Domain.spawn (update a (fun x -> x +. 1.))
400 let d2 = Domain.spawn (update a (fun x -> 2. *. x +. 1.))
401 let () = Domain.join d1; Domain.join d2
402 After executing this code, each field of the float array a is either 2.
405 , 3. , 4. or 5. . If atomicity is required, then the user must im‐
406 plement their own synchronization (for example, using Mutex.t ).
407 Data races
410 If two domains only access disjoint parts of the array, then the ob‐
411 served behaviour is the equivalent to some sequential interleaving of
412 the operations from the two domains.
413 A data race is said to occur when two domains access the same array el‐
415 ement without synchronization and at least one of the accesses is a
416 write. In the absence of data races, the observed behaviour is equiva‐
417 lent to some sequential interleaving of the operations from different
418 domains.
419 Whenever possible, data races should be avoided by using synchroniza‐
421 tion to mediate the accesses to the array elements.
422 Indeed, in the presence of data races, programs will not crash but the
424 observed behaviour may not be equivalent to any sequential interleaving
425 of operations from different domains. Nevertheless, even in the pres‐
426 ence of data races, a read operation will return the value of some
427 prior write to that location with a few exceptions.
428 Tearing
431 Float arrays have two supplementary caveats in the presence of data
432 races.
433 First, the blit operation might copy an array byte-by-byte. Data races
435 between such a blit operation and another operation might produce sur‐
436 prising values due to tearing: partial writes interleaved with other
437 operations can create float values that would not exist with a sequen‐
438 tial execution.
439 For instance, at the end of
441 let zeros = Float.Array.make size 0.
442 let max_floats = Float.Array.make size Float.max_float
443 let res = Float.Array.copy zeros
444 let d1 = Domain.spawn (fun () -> Float.Array.blit zeros 0 res 0 size)
445 let d2 = Domain.spawn (fun () -> Float.Array.blit max_floats 0 res 0 size)
446 let () = Domain.join d1; Domain.join d2
447 the res float array might contain values that are neither 0. nor
450 max_float .
451 Second, on 32-bit architectures, getting or setting a field involves
453 two separate memory accesses. In the presence of data races, the user
454 may observe tearing on any operation.
455OCamldoc 2023-07-20 Float.ArrayLabels(3)