17 Unsafe Operations
(require racket/unsafe/ops) | package: base |
All functions and forms provided by racket/base and racket check their arguments to ensure that the arguments conform to contracts and other constraints. For example, vector-ref checks its arguments to ensure that the first argument is a vector, that the second argument is an exact integer, and that the second argument is between 0 and one less than the vector’s length, inclusive.
Functions provided by racket/unsafe/ops are unsafe. They have certain constraints, but the constraints are not checked, which allows the system to generate and execute faster code. If arguments violate an unsafe function’s constraints, the function’s behavior and result is unpredictable, and the entire system can crash or become corrupted.
All of the exported bindings of racket/unsafe/ops are protected in the sense of protect-out, so access to unsafe operations can be prevented by adjusting the code inspector (see Code Inspectors).
17.1 Unsafe Numeric Operations
procedure
(unsafe-fx+ a ...) → fixnum?
a : fixnum?
procedure
(unsafe-fx- a b ...) → fixnum?
a : fixnum? b : fixnum?
procedure
(unsafe-fx* a ...) → fixnum?
a : fixnum?
procedure
(unsafe-fxquotient a b) → fixnum?
a : fixnum? b : fixnum?
procedure
(unsafe-fxremainder a b) → fixnum?
a : fixnum? b : fixnum?
procedure
(unsafe-fxmodulo a b) → fixnum?
a : fixnum? b : fixnum?
procedure
(unsafe-fxabs a) → fixnum?
a : fixnum?
Changed in version 7.0.0.13 of package base: Allow zero or more arguments for unsafe-fx+ and unsafe-fx* and allow one or more arguments for unsafe-fx-.
procedure
(unsafe-fxand a ...) → fixnum?
a : fixnum?
procedure
(unsafe-fxior a ...) → fixnum?
a : fixnum?
procedure
(unsafe-fxxor a ...) → fixnum?
a : fixnum?
procedure
(unsafe-fxnot a) → fixnum?
a : fixnum?
procedure
(unsafe-fxlshift a b) → fixnum?
a : fixnum? b : fixnum?
procedure
(unsafe-fxrshift a b) → fixnum?
a : fixnum? b : fixnum?
Changed in version 7.0.0.13 of package base: Allow zero or more arguments for unsafe-fxand, unsafe-fxior, and unsafe-fxxor.
procedure
(unsafe-fx= a b ...) → boolean?
a : fixnum? b : fixnum?
procedure
(unsafe-fx< a b ...) → boolean?
a : fixnum? b : fixnum?
procedure
(unsafe-fx> a b ...) → boolean?
a : fixnum? b : fixnum?
procedure
(unsafe-fx<= a b ...) → boolean?
a : fixnum? b : fixnum?
procedure
(unsafe-fx>= a b ...) → boolean?
a : fixnum? b : fixnum?
procedure
(unsafe-fxmin a b ...) → fixnum?
a : fixnum? b : fixnum?
procedure
(unsafe-fxmax a b ...) → fixnum?
a : fixnum? b : fixnum?
Changed in version 7.0.0.13 of package base: Allow one or more argument, instead of allowing just two.
procedure
(unsafe-fl+ a ...) → flonum?
a : flonum?
procedure
(unsafe-fl- a b ...) → flonum?
a : flonum? b : flonum?
procedure
(unsafe-fl* a ...) → flonum?
a : flonum?
procedure
(unsafe-fl/ a b ...) → flonum?
a : flonum? b : flonum?
procedure
(unsafe-flabs a) → flonum?
a : flonum?
Changed in version 7.0.0.13 of package base: Allow zero or more arguments for unsafe-fl+ and unsafe-fl* and one or more arguments for unsafe-fl- and unsafe-fl/.
procedure
(unsafe-fl= a b ...) → boolean?
a : flonum? b : flonum?
procedure
(unsafe-fl< a b ...) → boolean?
a : flonum? b : flonum?
procedure
(unsafe-fl> a b ...) → boolean?
a : flonum? b : flonum?
procedure
(unsafe-fl<= a b ...) → boolean?
a : flonum? b : flonum?
procedure
(unsafe-fl>= a b ...) → boolean?
a : flonum? b : flonum?
procedure
(unsafe-flmin a b ...) → flonum?
a : flonum? b : flonum?
procedure
(unsafe-flmax a b ...) → flonum?
a : flonum? b : flonum?
Changed in version 7.0.0.13 of package base: Allow one or more argument, instead of allowing just two.
procedure
(unsafe-flround a) → flonum?
a : flonum?
procedure
(unsafe-flfloor a) → flonum?
a : flonum?
procedure
(unsafe-flceiling a) → flonum?
a : flonum?
procedure
(unsafe-fltruncate a) → flonum?
a : flonum?
procedure
(unsafe-flsin a) → flonum?
a : flonum?
procedure
(unsafe-flcos a) → flonum?
a : flonum?
procedure
(unsafe-fltan a) → flonum?
a : flonum?
procedure
(unsafe-flasin a) → flonum?
a : flonum?
procedure
(unsafe-flacos a) → flonum?
a : flonum?
procedure
(unsafe-flatan a) → flonum?
a : flonum?
procedure
(unsafe-fllog a) → flonum?
a : flonum?
procedure
(unsafe-flexp a) → flonum?
a : flonum?
procedure
(unsafe-flsqrt a) → flonum?
a : flonum?
procedure
(unsafe-flexpt a b) → flonum?
a : flonum? b : flonum?
procedure
→
(and/c complex? (lambda (c) (flonum? (real-part c))) (lambda (c) (flonum? (imag-part c)))) a : flonum? b : flonum?
procedure
(unsafe-flreal-part a) → flonum?
a :
(and/c complex? (lambda (c) (flonum? (real-part c))) (lambda (c) (flonum? (imag-part c))))
procedure
(unsafe-flimag-part a) → flonum?
a :
(and/c complex? (lambda (c) (flonum? (real-part c))) (lambda (c) (flonum? (imag-part c))))
procedure
(unsafe-fx->fl a) → flonum?
a : fixnum?
procedure
(unsafe-fl->fx a) → fixnum?
a : flonum?
procedure
(unsafe-flrandom rand-gen) → (and flonum? (>/c 0) (</c 1))
rand-gen : pseudo-random-generator?
17.2 Unsafe Character Operations
procedure
(unsafe-char=? a b ...) → boolean?
a : char? b : char?
procedure
(unsafe-char<? a b ...) → boolean?
a : char? b : char?
procedure
(unsafe-char>? a b ...) → boolean?
a : char? b : char?
procedure
(unsafe-char<=? a b ...) → boolean?
a : char? b : char?
procedure
(unsafe-char>=? a b ...) → boolean?
a : char? b : char?
procedure
(unsafe-char->integer a) → fixnum?
a : char?
Added in version 7.0.0.14 of package base.
17.3 Unsafe Data Extraction
procedure
(unsafe-car p) → any/c
p : pair?
procedure
(unsafe-cdr p) → any/c
p : pair?
procedure
(unsafe-mcar p) → any/c
p : mpair?
procedure
(unsafe-mcdr p) → any/c
p : mpair?
procedure
(unsafe-set-mcar! p v) → void?
p : mpair? v : any/c
procedure
(unsafe-set-mcdr! p v) → void?
p : mpair? v : any/c
procedure
(unsafe-list-ref lst pos) → any/c
lst : pair? pos : (and/c exact-nonnegative-integer? fixnum?)
procedure
(unsafe-list-tail lst pos) → any/c
lst : any/c pos : (and/c exact-nonnegative-integer? fixnum?)
procedure
(unsafe-unbox b) → fixnum?
b : box?
procedure
(unsafe-set-box! b k) → void?
b : box? k : fixnum?
procedure
(unsafe-unbox* v) → any/c
v : (and/c box? (not/c impersonator?))
procedure
(unsafe-set-box*! v val) → void?
v : (and/c box? (not/c impersonator?)) val : any/c
procedure
(unsafe-box*-cas! loc old new) → boolean?
loc : box? old : any/c new : any/c
procedure
(unsafe-vector-length v) → fixnum?
v : vector?
procedure
(unsafe-vector-ref v k) → any/c
v : vector? k : fixnum?
procedure
(unsafe-vector-set! v k val) → void?
v : vector? k : fixnum? val : any/c
procedure
(unsafe-vector*-length v) → fixnum?
v : (and/c vector? (not/c impersonator?))
procedure
(unsafe-vector*-ref v k) → any/c
v : (and/c vector? (not/c impersonator?)) k : fixnum?
procedure
(unsafe-vector*-set! v k val) → void?
v : (and/c vector? (not/c impersonator?)) k : fixnum? val : any/c
procedure
(unsafe-vector*-cas! v k old-val new-val) → boolean?
v : (and/c vector? (not/c impersonator?)) k : fixnum? old-val : any/c new-val : any/c
A vector’s size can never be larger than a fixnum, so even vector-length always returns a fixnum.
Changed in version 6.11.0.2 of package base: Added unsafe-vector*-cas!.
procedure
→ (and/c vector? immutable?) v : (and/c vector? (not/c impersonator?))
Added in version 7.7.0.6 of package base.
procedure
(unsafe-string-length str) → fixnum?
str : string?
procedure
(unsafe-string-ref str k)
→ (and/c char? (lambda (ch) (<= 0 (char->integer ch) 255))) str : string? k : fixnum?
procedure
(unsafe-string-set! str k ch) → void?
str : (and/c string? (not/c immutable?)) k : fixnum? ch : char?
procedure
→ (and/c string? immutable?) str : string?
Added in version 7.7.0.6 of package base.
procedure
(unsafe-bytes-length bstr) → fixnum?
bstr : bytes?
procedure
(unsafe-bytes-ref bstr k) → byte?
bstr : bytes? k : fixnum?
procedure
(unsafe-bytes-set! bstr k b) → void?
bstr : (and/c bytes? (not/c immutable?)) k : fixnum? b : byte?
procedure
(unsafe-bytes-copy! dest dest-start src [ src-start src-end]) → void? dest : (and/c bytes? (not/c immutable?)) dest-start : fixnum? src : bytes? src-start : fixnum? = 0 src-end : fixnum? = (bytes-length src)
Changed in version 7.5.0.15 of package base: Added unsafe-bytes-copy!.
procedure
→ (and/c bytes? immutable?) bstr : bytes?
Added in version 7.7.0.6 of package base.
procedure
v : fxvector?
procedure
(unsafe-fxvector-ref v k) → fixnum?
v : fxvector? k : fixnum?
procedure
(unsafe-fxvector-set! v k x) → void?
v : fxvector? k : fixnum? x : fixnum?
procedure
v : flvector?
procedure
(unsafe-flvector-ref v k) → flonum?
v : flvector? k : fixnum?
procedure
(unsafe-flvector-set! v k x) → void?
v : flvector? k : fixnum? x : flonum?
procedure
(unsafe-f64vector-ref vec k) → flonum?
vec : f64vector? k : fixnum?
procedure
(unsafe-f64vector-set! vec k n) → void?
vec : f64vector? k : fixnum? n : flonum?
procedure
(unsafe-s16vector-ref vec k) → (integer-in -32768 32767)
vec : s16vector? k : fixnum?
procedure
(unsafe-s16vector-set! vec k n) → void?
vec : s16vector? k : fixnum? n : (integer-in -32768 32767)
procedure
(unsafe-u16vector-ref vec k) → (integer-in 0 65535)
vec : u16vector? k : fixnum?
procedure
(unsafe-u16vector-set! vec k n) → void?
vec : u16vector? k : fixnum? n : (integer-in 0 65535)
procedure
(unsafe-struct-ref v k) → any/c
v : any/c k : fixnum?
procedure
(unsafe-struct-set! v k val) → void?
v : any/c k : fixnum? val : any/c
procedure
(unsafe-struct*-ref v k) → any/c
v : (not/c impersonator?) k : fixnum?
procedure
(unsafe-struct*-set! v k val) → void?
v : (not/c impersonator?) k : fixnum? val : any/c
procedure
(unsafe-struct*-cas! v k old-val new-val) → boolean?
v : (not/c impersonator?) k : fixnum? old-val : any/c new-val : any/c
Changed in version 6.11.0.2 of package base: Added unsafe-struct*-cas!.
Each unsafe ...-first and ...-next procedure may return, instead of a number index, an internal representation of a view into the hash structure, enabling faster iteration. The result of these ...-first and ...-next functions should be given as pos to the corresponding unsafe accessor functions.
If the pos provided to an accessor function for a mutable hash was formerly a valid hash index but is no longer a valid hash index for hash, and if bad-index-v is not provided, then the exn:fail:contract exception is raised. No behavior is specified for a pos that was never a valid hash index for hash. Note that bad-index-v argument is technically not useful for the unsafe-immutable-hash-iterate- functions, since an index cannot become invalid for an immutable hash.
Added in version 6.4.0.6 of package base.
Changed in version 7.0.0.10: Added the optional bad-index-v argument.
procedure
(unsafe-make-srcloc source line column position span) → srcloc? source : any/c line : (or/c exact-positive-integer? #f) column : (or/c exact-nonnegative-integer? #f) position : (or/c exact-positive-integer? #f) span : (or/c exact-nonnegative-integer? #f)
Added in version 7.2.0.10 of package base.
17.4 Unsafe Extflonum Operations
procedure
(unsafe-extfl+ a b) → extflonum?
a : extflonum? b : extflonum?
procedure
(unsafe-extfl- a b) → extflonum?
a : extflonum? b : extflonum?
procedure
(unsafe-extfl* a b) → extflonum?
a : extflonum? b : extflonum?
procedure
(unsafe-extfl/ a b) → extflonum?
a : extflonum? b : extflonum?
procedure
(unsafe-extflabs a) → extflonum?
a : extflonum?
procedure
(unsafe-extfl= a b) → boolean?
a : extflonum? b : extflonum?
procedure
(unsafe-extfl< a b) → boolean?
a : extflonum? b : extflonum?
procedure
(unsafe-extfl> a b) → boolean?
a : extflonum? b : extflonum?
procedure
(unsafe-extfl<= a b) → boolean?
a : extflonum? b : extflonum?
procedure
(unsafe-extfl>= a b) → boolean?
a : extflonum? b : extflonum?
procedure
(unsafe-extflmin a b) → extflonum?
a : extflonum? b : extflonum?
procedure
(unsafe-extflmax a b) → extflonum?
a : extflonum? b : extflonum?
procedure
(unsafe-extflround a) → extflonum?
a : extflonum?
procedure
(unsafe-extflfloor a) → extflonum?
a : extflonum?
procedure
a : extflonum?
procedure
a : extflonum?
procedure
(unsafe-extflsin a) → extflonum?
a : extflonum?
procedure
(unsafe-extflcos a) → extflonum?
a : extflonum?
procedure
(unsafe-extfltan a) → extflonum?
a : extflonum?
procedure
(unsafe-extflasin a) → extflonum?
a : extflonum?
procedure
(unsafe-extflacos a) → extflonum?
a : extflonum?
procedure
(unsafe-extflatan a) → extflonum?
a : extflonum?
procedure
(unsafe-extfllog a) → extflonum?
a : extflonum?
procedure
(unsafe-extflexp a) → extflonum?
a : extflonum?
procedure
(unsafe-extflsqrt a) → extflonum?
a : extflonum?
procedure
(unsafe-extflexpt a b) → extflonum?
a : extflonum? b : extflonum?
procedure
(unsafe-fx->extfl a) → extflonum?
a : fixnum?
procedure
(unsafe-extfl->fx a) → fixnum?
a : extflonum?
procedure
v : extflvector?
procedure
(unsafe-extflvector-ref v k) → extflonum?
v : extflvector? k : fixnum?
procedure
(unsafe-extflvector-set! v k x) → void?
v : extflvector? k : fixnum? x : extflonum?
17.5 Unsafe Impersonators and Chaperones
procedure
(unsafe-impersonate-procedure proc replacement-proc prop prop-val ... ...) → (and/c procedure? impersonator?) proc : procedure? replacement-proc : procedure? prop : impersonator-property? prop-val : any
If proc is itself an impersonator that is derived from impersonate-procedure* or chaperone-procedure*, beware that replacement-proc will not be able to call it correctly. Specifically, the impersonator produced by unsafe-impersonate-procedure will not get passed to a wrapper procedure that was supplied to impersonate-procedure* or chaperone-procedure* to generate proc.
Finally, unlike impersonate-procedure, unsafe-impersonate-procedure does not specially handle impersonator-prop:application-mark as a prop.
The unsafety of unsafe-impersonate-procedure is limited to the above differences from impersonate-procedure. The contracts on the arguments of unsafe-impersonate-procedure are checked when the arguments are supplied.
(define log1-args '()) (define log1-results '()) (define wrap-f1 (λ (f) (impersonate-procedure f (λ (arg) (set! log1-args (cons arg log1-args)) (values (λ (res) (set! log1-results (cons res log1-results)) res) arg))))) (define log2-args '()) (define log2-results '()) (define wrap-f2 (λ (f) (unsafe-impersonate-procedure f (λ (arg) (set! log2-args (cons arg log2-args)) (let ([res (f arg)]) (set! log2-results (cons res log2-results)) res)))))
Added in version 6.4.0.4 of package base.
procedure
(unsafe-chaperone-procedure proc wrapper-proc prop prop-val ... ...) → (and/c procedure? chaperone?) proc : procedure? wrapper-proc : procedure? prop : impersonator-property? prop-val : any
Added in version 6.4.0.4 of package base.
procedure
(unsafe-impersonate-vector vec replacement-vec prop prop-val ... ...) → (and/c vector? impersonator?) vec : vector? replacement-vec : (and/c vector? (not/c impersonator?)) prop : impersonator-property? prop-val : any/c
The result of unsafe-impersonate-vector is an impersonator of vec.
Added in version 6.9.0.2 of package base.
procedure
(unsafe-chaperone-vector vec replacement-vec prop prop-val ... ...) → (and/c vector? chaperone?) vec : vector? replacement-vec : (and/c vector? (not/c impersonator?)) prop : impersonator-property? prop-val : any/c
Added in version 6.9.0.2 of package base.
17.6 Unsafe Undefined
(require racket/unsafe/undefined) | package: base |
The constant unsafe-undefined is used internally as a placeholder value. For example, it is used by letrec as a value for a variable that has not yet been assigned a value. Unlike the undefined value exported by racket/undefined, however, the unsafe-undefined value should not leak as the result of a safe expression, and it should not be passed as an optional argument to a procedure (because it may count as “no value provided”). Expression results that potentially produce unsafe-undefined can be guarded by check-not-unsafe-undefined, so that an exception can be raised instead of producing an undefined value.
The unsafe-undefined value is always eq? to itself.
Added in version 6.0.1.2 of package base.
Changed in version 6.90.0.29: Procedures with optional arguments
sometimes use the unsafe-undefined
value internally to mean “no argument supplied.”
value
See above for important constraints on the use of unsafe-undefined.
procedure
(check-not-unsafe-undefined v sym)
→ (and/c any/c (not/c (one-of/c unsafe-undefined))) v : any/c sym : symbol?
procedure
v : any/c
When a field access would otherwise produce unsafe-undefined or when a field assignment would replace unsafe-undefined, the exn:fail:contract exception is raised.
The chaperone’s field-assignment check is disabled whenever
(continuation-mark-set-first #f prop:chaperone-unsafe-undefined) returns unsafe-undefined.
Thus, a field-initializing assignment—
The property value should be a list of symbols used as field names, but the list should be in reverse order of the structure’s fields. When a field access or assignment would produce or replace unsafe-undefined, the exn:fail:contract:variable exception is raised if a field name is provided by the structure property’s value, otherwise the exn:fail:contract exception is raised.