ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/Faster/README
(Generate patch)

Comparing Faster/README (file contents):
Revision 1.1 by root, Thu Mar 9 04:41:21 2006 UTC vs.
Revision 1.2 by root, Fri Mar 10 20:54:34 2006 UTC

1NAME 1NAME
2 Convert::Scalar - convert between different representations of perl 2 Faster - do some things faster
3 scalars
4 3
5SYNOPSIS 4SYNOPSIS
6 use Convert::Scalar; 5 use Faster;
6
7 perl -MFaster ...
7 8
8DESCRIPTION 9DESCRIPTION
9 This module exports various internal perl methods that change the 10 This module implements a very simple-minded JIT. It works by more or
10 internal representation or state of a perl scalar. All of these work 11 less translating every function it sees into a C program, compiling it
11 in-place, that is, they modify their scalar argument. No functions are 12 and then replacing the function by the compiled code.
12 exported by default.
13 13
14 The following export tags exist: 14 As a result, startup times are immense, as every function might lead to
15 a full-blown compilation.
15 16
16 :utf8 all functions with utf8 in their name 17 The speed improvements are also not great, you can expect 20% or so on
17 :taint all functions with taint in their name 18 average, for code that runs very often.
18 :refcnt all functions with refcnt in their name
19 :ok all *ok-functions.
20 19
21 utf8 scalar[, mode] 20 Faster is in the early stages of development. Due to its design its
22 Returns true when the given scalar is marked as utf8, false 21 relatively safe to use (it will either work or simply slowdown the
23 otherwise. If the optional mode argument is given, also forces the 22 program immensely, but rarely cause bugs).
24 interpretation of the string to utf8 (mode true) or plain bytes
25 (mode false). The actual (byte-) content is not changed. The return
26 value always reflects the state before any modification is done.
27 23
28 This function is useful when you "import" utf8-data into perl, or 24 Usage is very easy, just "use Faster" and every function called from
29 when some external function (e.g. storing/retrieving from a 25 then on will be compiled.
30 database) removes the utf8-flag.
31 26
32 utf8_on scalar 27 Right now, Faster will leave ltos of *.c, *.o and *.so files in /tmp,
33 Similar to "utf8 scalar, 1", but additionally returns the scalar 28 and it will even create those temporary files in an insecure manner, so
34 (the argument is still modified in-place). 29 watch out.
35 30
36 utf8_off scalar 31BUGS/LIMITATIONS
37 Similar to "utf8 scalar, 0", but additionally returns the scalar 32 Perl will check much less often for asynchronous signals in
38 (the argument is still modified in-place). 33 Faster-compiled code. It tries to check on every function call, loop
34 iteration and every I/O operator, though.
39 35
40 utf8_valid scalar [Perl 5.7] 36 The following things will disable Faster. If you manage to enable them
41 Returns true if the bytes inside the scalar form a valid utf8 37 at runtime, bad things will happen.
42 string, false otherwise (the check is independent of the actual
43 encoding perl thinks the string is in).
44 38
45 utf8_upgrade scalar 39 enabled tainting
46 Convert the string content of the scalar in-place to its 40 enabled debugging
47 UTF8-encoded form (and also returns it).
48 41
49 utf8_downgrade scalar[, fail_ok=0] 42 This will dramatically reduce Faster's performance:
50 Attempt to convert the string content of the scalar from
51 UTF8-encoded to ISO-8859-1. This may not be possible if the string
52 contains characters that cannot be represented in a single byte; if
53 this is the case, it leaves the scalar unchanged and either returns
54 false or, if "fail_ok" is not true (the default), croaks.
55 43
56 utf8_encode scalar 44 threads (but you don't care about speed if you use threads anyway)
57 Convert the string value of the scalar to UTF8-encoded, but then
58 turn off the "SvUTF8" flag so that it looks like bytes to perl
59 again. (Might be removed in future versions).
60 45
61 utf8_length scalar 46 These constructs will force the use of the interpreter as soon as they
62 Returns the number of characters in the string, counting wide UTF8 47 are being executed, for the rest of the currently executed:
63 characters as a single character, independent of wether the scalar
64 is marked as containing bytes or mulitbyte characters.
65 48
66 unmagic scalar, type 49 .., ... (flipflop operators)
67 Remove the specified magic from the scalar (DANGEROUS!). 50 goto
68 51 next, redo (but not well-behaved last's)
69 weaken scalar 52 eval
70 Weaken a reference. (See also WeakRef). 53 require
71 54 any use of formats
72 taint scalar
73 Taint the scalar.
74
75 tainted scalar
76 returns true when the scalar is tainted, false otherwise.
77
78 untaint scalar
79 Remove the tainted flag from the specified scalar.
80
81 grow scalar, newlen
82 Sets the memory area used for the scalar to the given length, if the
83 current length is less than the new value. This does not affect the
84 contents of the scalar, but is only useful to "pre-allocate" memory
85 space if you know the scalar will grow. The return value is the
86 modified scalar (the scalar is modified in-place).
87
88 refcnt scalar[, newrefcnt]
89 Returns the current reference count of the given scalar and
90 optionally sets it to the given reference count.
91
92 refcnt_inc scalar
93 Increments the reference count of the given scalar inplace.
94
95 refcnt_dec scalar
96 Decrements the reference count of the given scalar inplace. Use
97 "weaken" instead if you understand what this function is fore.
98 Better yet: don't use this module in this case.
99
100 refcnt_rv scalar[, newrefcnt]
101 Works like "refcnt", but dereferences the given reference first.
102 This is useful to find the reference count of arrays or hashes,
103 which cnanot be passed directly. Remember that taking a reference of
104 some object increases it's reference count, so the reference count
105 used by the *_rv-functions tend to be one higher.
106
107 refcnt_inc_rv scalar
108 Works like "refcnt_inc", but dereferences the given reference first.
109
110 refcnt_dec_rv scalar
111 Works like "refcnt_dec", but dereferences the given reference first.
112
113 ok scalar
114 uok scalar
115 rok scalar
116 pok scalar
117 nok scalar
118 niok scalar
119 Calls SvOK, SvUOK, SvROK, SvPOK, SvNOK or SvNIOK on the given
120 scalar, respectively.
121
122 CANDIDATES FOR FUTURE RELEASES
123 The following API functions (perlapi) are considered for future
124 inclusion in this module If you want them, write me.
125
126 sv_upgrade
127 sv_pvn_force
128 sv_pvutf8n_force
129 the sv2xx family
130 55
131AUTHOR 56AUTHOR
132 Marc Lehmann <schmorp@schmorp.de> 57 Marc Lehmann <schmorp@schmorp.de>
133 http://home.schmorp.de/ 58 http://home.schmorp.de/
134 59

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines