-----------------------------------------------------------------------
--- $Id: primops.txt.pp,v 1.37 2005/11/25 09:46:19 simonmar Exp $
+--
+-- (c) 2010 The University of Glasgow
--
-- Primitive Operations and Types
--
+-- For more information on PrimOps, see
+-- http://hackage.haskell.org/trac/ghc/wiki/Commentary/PrimOps
+--
-----------------------------------------------------------------------
-- This file is processed by the utility program genprimopcode to produce
--
-- It should first be preprocessed.
--
--- To add a new primop, you currently need to update the following files:
---
--- - this file (ghc/compiler/prelude/primops.txt.pp), which includes
--- the type of the primop, and various other properties (its
--- strictness attributes, whether it is defined as a macro
--- or as out-of-line code, etc.)
---
--- - if the primop is inline (i.e. a macro), then:
--- ghc/compiler/AbsCUtils.lhs (dscCOpStmt)
--- defines the translation of the primop into simpler
--- abstract C operations.
---
--- - or, for an out-of-line primop:
--- ghc/includes/StgMiscClosures.h (just add the declaration)
--- ghc/rts/PrimOps.cmm (define it here)
--- ghc/rts/Linker.c (declare the symbol for GHCi)
---
--- - the User's Guide
+-- Information on how PrimOps are implemented and the steps necessary to
+-- add a new one can be found in the Commentary:
--
+-- http://hackage.haskell.org/trac/ghc/wiki/Commentary/PrimOps
-- This file is divided into named sections, each containing or more
-- primop entries. Section headers have the format:
primop NewArrayOp "newArray#" GenPrimOp
Int# -> a -> State# s -> (# State# s, MutableArray# s a #)
- {Create a new mutable array of specified size (in bytes),
+ {Create a new mutable array with the specified number of elements,
in the specified state thread,
with each element containing the specified initial value.}
with
with
has_side_effects = True
+primop SizeofArrayOp "sizeofArray#" GenPrimOp
+ Array# a -> Int#
+ {Return the number of elements in the array.}
+
+primop SizeofMutableArrayOp "sizeofMutableArray#" GenPrimOp
+ MutableArray# s a -> Int#
+ {Return the number of elements in the array.}
+
primop IndexArrayOp "indexArray#" GenPrimOp
Array# a -> Int# -> (# a #)
{Read from specified index of immutable array. Result is packaged into
section "Byte Arrays"
{Operations on {\tt ByteArray\#}. A {\tt ByteArray\#} is a just a region of
raw memory in the garbage-collected heap, which is not
- scanned for pointers. It carries its own size (in bytes,
- rounded up to the nearest multiple of a word). There are
+ scanned for pointers. It carries its own size (in bytes).
+ There are
three sets of operations for accessing byte array contents:
index for reading from immutable byte arrays, and read/write
for mutable byte arrays. Each set contains operations for a
primop SizeofByteArrayOp "sizeofByteArray#" GenPrimOp
ByteArray# -> Int#
- {Return the size of the array in bytes, rounded up to the nearest multiple
- of a word.}
+ {Return the size of the array in bytes.}
primop SizeofMutableByteArrayOp "sizeofMutableByteArray#" GenPrimOp
MutableByteArray# s -> Int#
- {Return the size of the array in bytes, rounded up to the nearest multiple
- of a word.}
+ {Return the size of the array in bytes.}
primop IndexByteArrayOp_Char "indexCharArray#" GenPrimOp
ByteArray# -> Int# -> Char#
out_of_line = True
has_side_effects = True
+primop CasMutVarOp "casMutVar#" GenPrimOp
+ MutVar# s a -> a -> a -> State# s -> (# State# s, Int#, a #)
+ with
+ out_of_line = True
+ has_side_effects = True
+
------------------------------------------------------------------------
section "Exceptions"
------------------------------------------------------------------------
-- raiseIO# needs to be a primop, because exceptions in the IO monad
-- must be *precise* - we don't want the strictness analyser turning
-- one kind of bottom into another, as it is allowed to do in pure code.
+--
+-- But we *do* want to know that it returns bottom after
+-- being applied to two arguments
primop RaiseIOOp "raiseIO#" GenPrimOp
a -> State# RealWorld -> (# State# RealWorld, b #)
with
+ strictness = { \ _arity -> mkStrictSig (mkTopDmdType [lazyDmd,lazyDmd] BotRes) }
out_of_line = True
has_side_effects = True
-primop BlockAsyncExceptionsOp "blockAsyncExceptions#" GenPrimOp
+primop MaskAsyncExceptionsOp "maskAsyncExceptions#" GenPrimOp
(State# RealWorld -> (# State# RealWorld, a #))
-> (State# RealWorld -> (# State# RealWorld, a #))
with
out_of_line = True
has_side_effects = True
-primop UnblockAsyncExceptionsOp "unblockAsyncExceptions#" GenPrimOp
+primop MaskUninterruptibleOp "maskUninterruptible#" GenPrimOp
(State# RealWorld -> (# State# RealWorld, a #))
-> (State# RealWorld -> (# State# RealWorld, a #))
with
out_of_line = True
has_side_effects = True
-primop AsyncExceptionsBlockedOp "asyncExceptionsBlocked#" GenPrimOp
+primop UnmaskAsyncExceptionsOp "unmaskAsyncExceptions#" GenPrimOp
+ (State# RealWorld -> (# State# RealWorld, a #))
+ -> (State# RealWorld -> (# State# RealWorld, a #))
+ with
+ out_of_line = True
+ has_side_effects = True
+
+primop MaskStatus "getMaskingState#" GenPrimOp
State# RealWorld -> (# State# RealWorld, Int# #)
with
out_of_line = True
has_side_effects = True
primop ThreadStatusOp "threadStatus#" GenPrimOp
- ThreadId# -> State# RealWorld -> (# State# RealWorld, Int# #)
+ ThreadId# -> State# RealWorld -> (# State# RealWorld, Int#, Int#, Int# #)
with
out_of_line = True
has_side_effects = True
has_side_effects = True
out_of_line = True
+primop NumSparks "numSparks#" GenPrimOp
+ State# s -> (# State# s, Int# #)
+ { Returns the number of sparks in the local spark pool. }
+ with
+ has_side_effects = True
+ out_of_line = True
+
-- HWL: The first 4 Int# in all par... annotations denote:
-- name, granularity info, size of result, degree of parallelism
-- Same structure as _seq_ i.e. returns Int#
{\tt inline} function expands to the identity function in Phase zero; so its
use imposes no overhead.
- If the function is defined in another module, GHC only exposes its inlining
- in the interface file if the function is sufficiently small that it might be
- inlined by the automatic mechanism. There is currently no way to tell GHC to
- expose arbitrarily-large functions in the interface file. (This shortcoming
- is something that could be fixed, with some kind of pragma.) }
+ It is good practice to mark the function with an INLINABLE pragma at
+ its definition, (a) so that GHC guarantees to expose its unfolding regardless
+ of size, and (b) so that you have control over exactly what is inlined. }
pseudoop "lazy"
a -> a
but never enters a function value.
It's also used to instantiate un-constrained type variables after type
- checking. For example
+ checking. For example, {\tt length} has type
+
+ {\tt length :: forall a. [a] -> Int}
+
+ and the list datacon for the empty list has type
+
+ {\tt [] :: forall a. [a]}
+
+ In order to compose these two terms as {\tt length []} a type
+ application is required, but there is no constraint on the
+ choice. In this situation GHC uses {\tt Any}:
- {\tt length Any []}
+ {\tt length Any ([] Any)}
Annoyingly, we sometimes need {\tt Any}s of other kinds, such as {\tt (* -> *)} etc.
This is a bit like tuples. We define a couple of useful ones here,
projects / ghc-hetmet.git / blobdiff