Artifact
1f26cd582b2cf523d0c46784c3f45207e568cfd7:
0000: 2e 54 48 20 54 52 41 4d 50 4f 4c 49 4e 45 20 33 .TH TRAMPOLINE 3
0010: 20 22 32 35 20 4f 63 74 6f 62 65 72 20 31 39 39 "25 October 199
0020: 37 22 0a 2e 53 48 20 4e 41 4d 45 0a 74 72 61 6d 7"..SH NAME.tram
0030: 70 6f 6c 69 6e 65 20 5c 2d 20 63 6c 6f 73 75 72 poline \- closur
0040: 65 73 20 61 73 20 66 69 72 73 74 2d 63 6c 61 73 es as first-clas
0050: 73 20 43 20 66 75 6e 63 74 69 6f 6e 73 0a 2e 53 s C functions..S
0060: 48 20 53 59 4e 4f 50 53 49 53 0a 2e 42 20 23 69 H SYNOPSIS..B #i
0070: 6e 63 6c 75 64 65 20 3c 74 72 61 6d 70 6f 6c 69 nclude <trampoli
0080: 6e 65 2e 68 3e 0a 2e 4c 50 0a 2e 42 20 66 75 6e ne.h>..LP..B fun
0090: 63 74 69 6f 6e 20 3d 20 61 6c 6c 6f 63 5f 74 72 ction = alloc_tr
00a0: 61 6d 70 6f 6c 69 6e 65 28 61 64 64 72 65 73 73 ampoline(address
00b0: 2c 20 76 61 72 69 61 62 6c 65 2c 20 64 61 74 61 , variable, data
00c0: 29 3b 0a 2e 4c 50 0a 2e 42 20 66 72 65 65 5f 74 );..LP..B free_t
00d0: 72 61 6d 70 6f 6c 69 6e 65 28 66 75 6e 63 74 69 rampoline(functi
00e0: 6f 6e 29 3b 0a 2e 4c 50 0a 2e 6e 66 0a 2e 42 20 on);..LP..nf..B
00f0: 69 73 5f 74 72 61 6d 70 6f 6c 69 6e 65 28 66 75 is_trampoline(fu
0100: 6e 63 74 69 6f 6e 29 0a 2e 42 20 74 72 61 6d 70 nction)..B tramp
0110: 6f 6c 69 6e 65 5f 61 64 64 72 65 73 73 28 66 75 oline_address(fu
0120: 6e 63 74 69 6f 6e 29 0a 2e 42 20 74 72 61 6d 70 nction)..B tramp
0130: 6f 6c 69 6e 65 5f 76 61 72 69 61 62 6c 65 28 66 oline_variable(f
0140: 75 6e 63 74 69 6f 6e 29 0a 2e 42 20 74 72 61 6d unction)..B tram
0150: 70 6f 6c 69 6e 65 5f 64 61 74 61 28 66 75 6e 63 poline_data(func
0160: 74 69 6f 6e 29 0a 2e 66 69 0a 2e 53 48 20 44 45 tion)..fi..SH DE
0170: 53 43 52 49 50 54 49 4f 4e 0a 2e 4c 50 0a 54 68 SCRIPTION..LP.Th
0180: 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 69 6d ese functions im
0190: 70 6c 65 6d 65 6e 74 0a 2e 49 20 63 6c 6f 73 75 plement..I closu
01a0: 72 65 73 0a 61 73 20 66 69 72 73 74 2d 63 6c 61 res.as first-cla
01b0: 73 73 20 43 20 66 75 6e 63 74 69 6f 6e 73 2e 0a ss C functions..
01c0: 41 20 63 6c 6f 73 75 72 65 20 63 6f 6e 73 69 73 A closure consis
01d0: 74 73 20 6f 66 20 61 20 72 65 67 75 6c 61 72 20 ts of a regular
01e0: 43 20 66 75 6e 63 74 69 6f 6e 20 61 6e 64 20 61 C function and a
01f0: 20 70 69 65 63 65 20 6f 66 20 64 61 74 61 0a 77 piece of data.w
0200: 68 69 63 68 20 67 65 74 73 20 70 61 73 73 65 64 hich gets passed
0210: 20 74 6f 20 74 68 65 20 43 20 66 75 6e 63 74 69 to the C functi
0220: 6f 6e 20 77 68 65 6e 20 74 68 65 20 63 6c 6f 73 on when the clos
0230: 75 72 65 20 69 73 20 63 61 6c 6c 65 64 2e 0a 0a ure is called...
0240: 43 6c 6f 73 75 72 65 73 20 61 73 0a 2e 49 20 66 Closures as..I f
0250: 69 72 73 74 2d 63 6c 61 73 73 20 43 20 66 75 6e irst-class C fun
0260: 63 74 69 6f 6e 73 0a 6d 65 61 6e 73 20 74 68 61 ctions.means tha
0270: 74 20 74 68 65 79 20 66 69 74 20 69 6e 74 6f 20 t they fit into
0280: 61 20 66 75 6e 63 74 69 6f 6e 0a 70 6f 69 6e 74 a function.point
0290: 65 72 20 61 6e 64 20 63 61 6e 20 62 65 20 63 61 er and can be ca
02a0: 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6c 69 6b lled exactly lik
02b0: 65 20 61 6e 79 20 6f 74 68 65 72 20 43 20 66 75 e any other C fu
02c0: 6e 63 74 69 6f 6e 2e 0a 2e 49 42 20 66 75 6e 63 nction...IB func
02d0: 74 69 6f 6e 20 22 20 3d 20 61 6c 6c 6f 63 5f 74 tion " = alloc_t
02e0: 72 61 6d 70 6f 6c 69 6e 65 28 22 20 61 64 64 72 rampoline(" addr
02f0: 65 73 73 20 22 2c 20 22 20 76 61 72 69 61 62 6c ess ", " variabl
0300: 65 20 22 2c 20 22 20 64 61 74 61 20 22 29 22 0a e ", " data ")".
0310: 61 6c 6c 6f 63 61 74 65 73 20 61 20 63 6c 6f 73 allocates a clos
0320: 75 72 65 2e 20 57 68 65 6e 0a 2e 49 20 66 75 6e ure. When..I fun
0330: 63 74 69 6f 6e 0a 67 65 74 73 20 63 61 6c 6c 65 ction.gets calle
0340: 64 2c 20 69 74 20 73 74 6f 72 65 73 0a 2e 49 20 d, it stores..I
0350: 64 61 74 61 0a 69 6e 20 74 68 65 20 76 61 72 69 data.in the vari
0360: 61 62 6c 65 0a 2e 49 20 76 61 72 69 61 62 6c 65 able..I variable
0370: 0a 61 6e 64 20 63 61 6c 6c 73 20 74 68 65 20 43 .and calls the C
0380: 20 66 75 6e 63 74 69 6f 6e 20 61 74 0a 2e 49 52 function at..IR
0390: 20 61 64 64 72 65 73 73 20 2e 0a 54 68 65 20 66 address ..The f
03a0: 75 6e 63 74 69 6f 6e 20 61 74 0a 2e 49 20 61 64 unction at..I ad
03b0: 64 72 65 73 73 0a 69 73 20 72 65 73 70 6f 6e 73 dress.is respons
03c0: 69 62 6c 65 20 66 6f 72 20 66 65 74 63 68 69 6e ible for fetchin
03d0: 67 0a 2e 49 20 64 61 74 61 0a 6f 75 74 20 6f 66 g..I data.out of
03e0: 0a 2e 49 20 76 61 72 69 61 62 6c 65 0a 69 6d 6d ..I variable.imm
03f0: 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 ediately, before
0400: 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 61 6e execution of an
0410: 79 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e y other function
0420: 20 63 61 6c 6c 2e 0a 0a 54 68 69 73 20 69 73 20 call...This is
0430: 6d 75 63 68 20 6c 69 6b 65 0a 2e 42 52 20 67 63 much like..BR gc
0440: 63 20 22 27 73 22 0a 6c 6f 63 61 6c 20 66 75 6e c "'s".local fun
0450: 63 74 69 6f 6e 73 2c 20 65 78 63 65 70 74 20 74 ctions, except t
0460: 68 61 74 20 74 68 65 20 47 4e 55 20 43 20 6c 6f hat the GNU C lo
0470: 63 61 6c 20 66 75 6e 63 74 69 6f 6e 73 20 68 61 cal functions ha
0480: 76 65 20 64 79 6e 61 6d 69 63 20 65 78 74 65 6e ve dynamic exten
0490: 74 0a 28 69 2e 65 2e 20 61 72 65 20 64 65 61 6c t.(i.e. are deal
04a0: 6c 6f 63 61 74 65 64 20 77 68 65 6e 20 74 68 65 located when the
04b0: 20 63 72 65 61 74 69 6e 67 20 66 75 6e 63 74 69 creating functi
04c0: 6f 6e 20 72 65 74 75 72 6e 73 29 2c 20 77 68 69 on returns), whi
04d0: 6c 65 0a 2e 49 20 74 72 61 6d 70 6f 6c 69 6e 65 le..I trampoline
04e0: 0a 70 72 6f 76 69 64 65 73 20 66 75 6e 63 74 69 .provides functi
04f0: 6f 6e 73 20 77 69 74 68 20 69 6e 64 65 66 69 6e ons with indefin
0500: 69 74 65 20 65 78 74 65 6e 74 3a 0a 2e 49 20 66 ite extent:..I f
0510: 75 6e 63 74 69 6f 6e 0a 69 73 20 6f 6e 6c 79 20 unction.is only
0520: 64 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e deallocated when
0530: 0a 2e 42 49 20 66 72 65 65 5f 74 72 61 6d 70 6f ..BI free_trampo
0540: 6c 69 6e 65 28 20 66 75 6e 63 74 69 6f 6e 20 29 line( function )
0550: 0a 69 73 20 63 61 6c 6c 65 64 2e 0a 0a 2e 42 49 .is called....BI
0560: 20 22 69 73 5f 74 72 61 6d 70 6f 6c 69 6e 65 28 "is_trampoline(
0570: 22 20 66 75 6e 63 74 69 6f 6e 20 22 29 22 0a 63 " function ")".c
0580: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 hecks whether th
0590: 65 20 43 20 66 75 6e 63 74 69 6f 6e 0a 2e 49 20 e C function..I
05a0: 66 75 6e 63 74 69 6f 6e 0a 77 61 73 20 70 72 6f function.was pro
05b0: 64 75 63 65 64 20 62 79 20 61 20 63 61 6c 6c 20 duced by a call
05c0: 74 6f 0a 2e 49 52 20 61 6c 6c 6f 63 5f 74 72 61 to..IR alloc_tra
05d0: 6d 70 6f 6c 69 6e 65 20 2e 0a 49 66 20 74 68 69 mpoline ..If thi
05e0: 73 20 72 65 74 75 72 6e 73 20 74 72 75 65 2c 20 s returns true,
05f0: 74 68 65 20 61 72 67 75 6d 65 6e 74 73 20 67 69 the arguments gi
0600: 76 65 6e 20 74 6f 0a 2e 49 20 61 6c 6c 6f 63 5f ven to..I alloc_
0610: 74 72 61 6d 70 6f 6c 69 6e 65 0a 63 61 6e 20 62 trampoline.can b
0620: 65 20 72 65 74 72 69 65 76 65 64 3a 0a 2e 52 53 e retrieved:..RS
0630: 20 34 0a 2e 4c 50 0a 2e 42 49 20 22 74 72 61 6d 4..LP..BI "tram
0640: 70 6f 6c 69 6e 65 5f 61 64 64 72 65 73 73 28 22 poline_address("
0650: 20 66 75 6e 63 74 69 6f 6e 20 22 29 22 0a 72 65 function ")".re
0660: 74 75 72 6e 73 0a 2e 49 52 20 61 64 64 72 65 73 turns..IR addres
0670: 73 20 2c 0a 2e 4c 50 0a 2e 42 49 20 22 74 72 61 s ,..LP..BI "tra
0680: 6d 70 6f 6c 69 6e 65 5f 76 61 72 69 61 62 6c 65 mpoline_variable
0690: 28 22 20 66 75 6e 63 74 69 6f 6e 20 22 29 22 0a (" function ")".
06a0: 72 65 74 75 72 6e 73 0a 2e 49 52 20 76 61 72 69 returns..IR vari
06b0: 61 62 6c 65 20 2c 0a 2e 4c 50 0a 2e 42 49 20 22 able ,..LP..BI "
06c0: 74 72 61 6d 70 6f 6c 69 6e 65 5f 64 61 74 61 28 trampoline_data(
06d0: 22 20 66 75 6e 63 74 69 6f 6e 20 22 29 22 0a 72 " function ")".r
06e0: 65 74 75 72 6e 73 0a 2e 49 52 20 64 61 74 61 20 eturns..IR data
06f0: 2e 0a 2e 52 45 0a 0a 2e 53 48 20 53 45 45 20 41 ...RE...SH SEE A
0700: 4c 53 4f 0a 2e 42 52 20 67 63 63 20 28 31 29 2c LSO..BR gcc (1),
0710: 0a 2e 42 52 20 76 61 72 61 72 67 73 20 28 33 29 ..BR varargs (3)
0720: 2c 0a 2e 42 52 20 63 61 6c 6c 62 61 63 6b 20 28 ,..BR callback (
0730: 33 29 0a 0a 2e 53 48 20 42 55 47 53 0a 50 61 73 3)...SH BUGS.Pas
0740: 73 69 6e 67 20 74 68 65 20 64 61 74 61 20 74 68 sing the data th
0750: 72 6f 75 67 68 20 61 20 67 6c 6f 62 61 6c 20 76 rough a global v
0760: 61 72 69 61 62 6c 65 20 69 73 20 6e 6f 74 20 72 ariable is not r
0770: 65 65 6e 74 72 61 6e 74 2e 20 44 6f 6e 27 74 20 eentrant. Don't
0780: 63 61 6c 6c 0a 74 72 61 6d 70 6f 6c 69 6e 65 20 call.trampoline
0790: 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 77 functions from w
07a0: 69 74 68 69 6e 20 73 69 67 6e 61 6c 20 68 61 6e ithin signal han
07b0: 64 6c 65 72 73 2e 20 54 68 69 73 20 69 73 20 66 dlers. This is f
07c0: 69 78 65 64 20 69 6e 20 74 68 65 0a 2e 42 52 20 ixed in the..BR
07d0: 63 61 6c 6c 62 61 63 6b 20 28 33 29 0a 70 61 63 callback (3).pac
07e0: 6b 61 67 65 2e 0a 0a 2e 53 48 20 50 4f 52 54 49 kage....SH PORTI
07f0: 4e 47 0a 54 68 65 20 77 61 79 0a 2e 42 20 67 63 NG.The way..B gc
0800: 63 0a 62 75 69 6c 64 73 20 6c 6f 63 61 6c 20 66 c.builds local f
0810: 75 6e 63 74 69 6f 6e 73 20 69 73 20 64 65 73 63 unctions is desc
0820: 72 69 62 65 64 20 69 6e 20 74 68 65 20 67 63 63 ribed in the gcc
0830: 20 73 6f 75 72 63 65 2c 20 66 69 6c 65 0a 2e 52 source, file..R
0840: 49 20 67 63 63 2d 32 2e 36 2e 33 2f 63 6f 6e 66 I gcc-2.6.3/conf
0850: 69 67 2f 20 63 70 75 20 2f 20 63 70 75 20 2e 68 ig/ cpu / cpu .h
0860: 2e 0a 0a 2e 53 48 20 41 55 54 48 4f 52 0a 0a 42 ....SH AUTHOR..B
0870: 72 75 6e 6f 20 48 61 69 62 6c 65 20 3c 62 72 75 runo Haible <bru
0880: 6e 6f 40 63 6c 69 73 70 2e 6f 72 67 3e 0a 0a 2e no@clisp.org>...
0890: 53 48 20 41 43 4b 4e 4f 57 4c 45 44 47 45 4d 45 SH ACKNOWLEDGEME
08a0: 4e 54 53 0a 0a 4d 61 6e 79 20 69 64 65 61 73 20 NTS..Many ideas
08b0: 77 65 72 65 20 63 72 69 62 62 65 64 20 66 72 6f were cribbed fro
08c0: 6d 20 74 68 65 20 67 63 63 20 73 6f 75 72 63 65 m the gcc source
08d0: 2e 0a 0a ...