Changeset 16028 in project


Ignore:
Timestamp:
09/22/09 04:17:34 (10 years ago)
Author:
Kon Lovett
Message:

Rel 2.1.0

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/eggref/4/synch

    r14119 r16028  
    33== synch
    44
     5Simple critical region helpers.
     6
    57[[toc:]]
    68
     
    810== Documentation
    911
    10 Simple critical region helpers.
    11 
    12 === make-object/synch
    13 
    14 <procedure>(make-object/synch OBJECT [NAME]) => MUTEX</procedure>
    15 
    16 Returns a mutex with a mutex-specific value of {{OBJECT}}, and optional mutex
    17 {{NAME}}.
    18 
    19 {{NAME}} is either a symbol or a one element list of symbol. When a list the
    20 first element is used as the basis for a generated symbol. When a symbol it is
    21 used literally as the mutex name.
    22 
    23 When {{NAME}} is missing a generated symbol with the prefix '''{{synchobj}}''' is
    24 provided.
    25 
    26 === object?/synch
    27 
    28 <procedure>(object?/synch OBJECT [PREDICATE]) => BOOLEAN</procedure>
    29 
    30 Is the {{OBJECT}} a synchronized object - a mutex with a non-void mutex
    31 specific?
    32 
    33 The optional {{PREDICATE}} is used to verify the type of the mutex-specific
    34 binding. Otherwise any object is accepted.
    35 
    36 === Synchronized Invocation - Continuation Safe
     12=== Critical Regions
     13
     14Where {{MUTEXFORM}} below the following forms are accepted:
     15
     16; {{MUTEX}} : just a mutex
     17; {{(MUTEX [(LOCK-ARG ...) [(UNLOCK-ARG ...)]])}} : mutx with optional lock and unlock arguments
     18
     19==== Synchronized Invocation - Continuation Safe
    3720
    3821These forms have the mutex lock/unlock wrapped in '''{{dynamic-wind}}'''.
    3922
    40 ==== synch
    41 
    42 <macro>(synch MUTEX [BODY ...]) => OBJECT</macro>
     23===== synch
     24
     25<macro>(synch MUTEXFORM [BODY ...]) => OBJECT</macro>
    4326
    4427Execute {{BODY ...}} while {{MUTEX}} locked.
     
    4629Returns the result of {{BODY ...}}.
    4730
    48 ==== synch-with
    49 
    50 <macro>(synch-with MUTEX VARIABLE [BODY ...]) => OBJECT</macro>
     31===== synch-with
     32
     33<macro>(synch-with MUTEXFORM VARIABLE [BODY ...]) => OBJECT</macro>
    5134
    5235Execute {{BODY ...}} while {{MUTEX}} locked and the mutex-specific of {{MUTEX}}
     
    5538Returns the result of {{BODY ...}}.
    5639
    57 ==== call/synch
    58 
    59 <macro>(call/synch MUTEX PROCEDURE [ARGUMENTS ...]) => OBJECT</macro>
     40===== call/synch
     41
     42<macro>(call/synch MUTEXFORM PROCEDURE [ARGUMENTS ...]) => OBJECT</macro>
    6043
    6144Invoke {{PROCEDURE}} on the argument list {{ARGUMENTS ...}} while {{MUTEX}}
     
    6447Returns the result of the {{PROCEDURE}} invocation.
    6548
    66 ==== call-with/synch
    67 
    68 <macro>(call-with/synch MUTEX PROCEDURE [ARGUMENTS ...]) => OBJECT</macro>
     49===== call-with/synch
     50
     51<macro>(call-with/synch MUTEXFORM PROCEDURE [ARGUMENTS ...]) => OBJECT</macro>
    6952
    7053Invoke {{PROCEDURE}} on the mutex-specific of {{MUTEX}}
     
    7356Returns the result of the {{PROCEDURE}} invocation.
    7457
    75 ==== apply/synch
    76 
    77 <macro>(apply/synch MUTEX PROCEDURE [ARGUMENTS ...]) => OBJECT</macro>
     58===== apply/synch
     59
     60<macro>(apply/synch MUTEXFORM PROCEDURE [ARGUMENTS ...]) => OBJECT</macro>
    7861
    7962Apply {{PROCEDURE}} to the argument list {{ARGUMENTS ...}} while {{MUTEX}}
     
    8265Returns the result of the {{PROCEDURE}} application.
    8366
    84 ==== apply-with/synch
    85 
    86 <macro>(apply-with/synch MUTEX PROCEDURE [ARGUMENTS ...]) => OBJECT</macro>
     67===== apply-with/synch
     68
     69<macro>(apply-with/synch MUTEXFORM PROCEDURE [ARGUMENTS ...]) => OBJECT</macro>
    8770
    8871Apply {{PROCEDURE}} to the mutex-specific of {{MUTEX}}) and the {{ARGUMENTS ...}}
     
    9174Returns the result of the {{PROCEDURE}} application.
    9275
    93 ==== synch/lock
    94 
    95 <macro>(synch/lock MUTEX [BODY ...]) => OBJECT</macro>
     76===== synch/lock
     77
     78<macro>(synch/lock MUTEXFORM [BODY ...]) => OBJECT</macro>
    9679
    9780Execute {{BODY ...}} while {{MUTEX}} locked, and leave mutex locked.
     
    9982Returns the result of {{BODY ...}}.
    10083
    101 ==== synch/unlock
    102 
    103 <macro>(synch/unlock MUTEX [BODY ...]) => OBJECT</macro>
     84===== synch/unlock
     85
     86<macro>(synch/unlock MUTEXFORM [BODY ...]) => OBJECT</macro>
    10487
    10588Execute {{BODY ...}} while {{MUTEX}} locked, and leave mutex unlocked.
     
    11093executing the {{BODY}}.
    11194
    112 ==== let/synch
     95===== let/synch
    11396
    11497<macro>(let/synch BINDINGS [BODY ...]) => OBJECT</macro>
    11598
    116 {{BINDINGS}} is a list of {{(VARIABLE MUTEX)}}.
    117 
    118 Expands into a nested {{(synch-with MUTEX VARIABLE ...}} form, a '''{{synch-with}}'''
     99{{BINDINGS}} is a list of {{(VARIABLE MUTEXFORM)}}.
     100
     101Expands into a nested {{(synch-with MUTEXFORM VARIABLE ...}} form, a '''{{synch-with}}'''
    119102for each binding pair in {{BINDINGS}}. The leftmost binding pair is the
    120103outermost.
     
    122105Returns the result of {{BODY ...}}.
    123106
    124 ==== set!/synch
    125 
    126 <macro>(set!/synch (VARIABLE MUTEX) [BODY ...]) => OBJECT</macro>
     107===== set!/synch
     108
     109<macro>(set!/synch (VARIABLE MUTEXFORM) [BODY ...]) => OBJECT</macro>
    127110
    128111While the {{MUTEX}} is locked, evaluates {{BODY ...}} with the {{VARIABLE}}
     
    132115Returns the new mutex-specific of {{MUTEX}}.
    133116
    134 ==== object/synch
    135 
    136 <macro>(object/synch MUTEX [BODY ...]) => OBJECT</macro>
     117===== object/synch
     118
     119<macro>(object/synch MUTEXFORM [BODY ...]) => OBJECT</macro>
    137120
    138121Execute {{BODY ...}} while {{MUTEX}} locked.
     
    143126Returns the result of {{BODY ...}}.
    144127
    145 ==== record/synch
     128===== record/synch
    146129
    147130<macro>(record/synch RECORD-SYMBOL RECORD-OBJECT [BODY ...]) => OBJECT</macro>
     
    165148</enscript>
    166149
    167 ==== record-synch/lock
     150===== record-synch/lock
    168151
    169152<macro>(record-synch/lock RECORD-SYMBOL RECORD-OBJECT [BODY ...]) => OBJECT</macro>
     
    176159{{RECORD-SYMBOL}} and {{RECORD-OBJECT}} are per '''{{record/synch}}'''.
    177160
    178 ==== record-synch/unlock
     161===== record-synch/unlock
    179162
    180163<macro>(record-synch/unlock RECORD-SYMBOL RECORD-OBJECT [BODY ...]) => OBJECT</macro>
     
    190173executing the {{BODY}}.
    191174
    192 === Synchronized Invocation - Continuation Unsafe
     175==== Synchronized Invocation - Continuation Unsafe
    193176
    194177These forms do not have the mutex lock/unlock wrapped in '''{{dynamic-wind}}''',
    195178otherwise the same behavior.
    196179
    197 ==== %call/synch
    198 
    199 <macro>(%call/synch MUTEX PROCEDURE [ARGUMENTS ...]) => OBJECT</macro>
    200 
    201 ==== %call-with/synch
    202 
    203 <macro>(%call-with/synch MUTEX PROCEDURE [ARGUMENTS ...]) => OBJECT</macro>
    204 
    205 ==== %apply/synch
    206 
    207 <macro>(%apply/synch MUTEX PROCEDURE [ARGUMENTS ...]) => OBJECT</macro>
    208 
    209 ==== %apply-with/synch
    210 
    211 <macro>(%apply-with/synch MUTEX PROCEDURE [ARGUMENTS ...]) => OBJECT</macro>
    212 
    213 ==== %synch
    214 
    215 <macro>(%synch MUTEX [BODY ...]) => OBJECT</macro>
    216 
    217 ==== %synch-with
    218 
    219 <macro>(%synch-with MUTEX VARIABLE [BODY ...]) => OBJECT</macro>
    220 
    221 ==== %synch/lock
    222 
    223 <macro>(%synch/lock MUTEX [BODY ...]) => OBJECT</macro>
    224 
    225 ==== %synch/unlock
    226 
    227 <macro>(%synch/unlock MUTEX [BODY ...]) => OBJECT</macro>
    228 
    229 ==== %let/synch
     180===== %call/synch
     181
     182<macro>(%call/synch MUTEXFORM PROCEDURE [ARGUMENTS ...]) => OBJECT</macro>
     183
     184===== %call-with/synch
     185
     186<macro>(%call-with/synch MUTEXFORM PROCEDURE [ARGUMENTS ...]) => OBJECT</macro>
     187
     188===== %apply/synch
     189
     190<macro>(%apply/synch MUTEXFORM PROCEDURE [ARGUMENTS ...]) => OBJECT</macro>
     191
     192===== %apply-with/synch
     193
     194<macro>(%apply-with/synch MUTEXFORM PROCEDURE [ARGUMENTS ...]) => OBJECT</macro>
     195
     196===== %synch
     197
     198<macro>(%synch MUTEXFORM [BODY ...]) => OBJECT</macro>
     199
     200===== %synch-with
     201
     202<macro>(%synch-with MUTEXFORM VARIABLE [BODY ...]) => OBJECT</macro>
     203
     204===== %synch/lock
     205
     206<macro>(%synch/lock MUTEXFORM [BODY ...]) => OBJECT</macro>
     207
     208===== %synch/unlock
     209
     210<macro>(%synch/unlock MUTEXFORM [BODY ...]) => OBJECT</macro>
     211
     212===== %let/synch
    230213
    231214<macro>(%let/synch BINDINGS [BODY ...]) => OBJECT</macro>
    232215
    233 ==== %set!/synch
     216===== %set!/synch
    234217
    235218<macro>(%set!/synch BINDING BODY ... => OBJECT</macro>
    236219
    237 ==== %object/synch
    238 
    239 <macro>(%object/synch MUTEX [BODY ...]) => OBJECT</macro>
    240 
    241 ==== %record/synch
     220===== %object/synch
     221
     222<macro>(%object/synch MUTEXFORM [BODY ...]) => OBJECT</macro>
     223
     224===== %record/synch
    242225
    243226<macro>(%record/synch RECORD-SYMBOL RECORD-OBJECT [BODY ...]) => OBJECT</macro>
    244227
    245 ==== %record-synch/lock
     228===== %record-synch/lock
    246229
    247230<macro>(%record-synch/lock RECORD-SYMBOL RECORD-OBJECT [BODY ...]) => OBJECT</macro>
    248231
    249 ==== %record-synch/unlock
     232===== %record-synch/unlock
    250233
    251234<macro>(%record-synch/unlock RECORD-SYMBOL RECORD-OBJECT [BODY ...]) => OBJECT</macro>
     235
     236
     237=== Object Synchronization
     238
     239==== make-object/synch
     240
     241<procedure>(make-object/synch OBJECT [NAME]) => MUTEX</procedure>
     242
     243Returns a mutex with a mutex-specific value of {{OBJECT}}, and optional mutex
     244{{NAME}}.
     245
     246{{NAME}} is either a symbol or a one element list of symbol. When a list the
     247first element is used as the basis for a generated symbol. When a symbol it is
     248used literally as the mutex name.
     249
     250When {{NAME}} is missing a generated symbol with the prefix '''{{synchobj}}''' is
     251provided.
     252
     253==== object?/synch
     254
     255<procedure>(object?/synch OBJECT [PREDICATE]) => BOOLEAN</procedure>
     256
     257Is the {{OBJECT}} a synchronized object - a mutex with a non-void mutex
     258specific?
     259
     260The optional {{PREDICATE}} is used to verify the type of the mutex-specific
     261binding. Otherwise any object is accepted.
     262
     263==== define-constructor/synch
     264
     265<macro>(define-constructor/synch CTORNAME [ID])</macro>
     266
     267<enscript language=scheme>
     268(define-constructor/synch make-hash-table hash-table/synch:)
     269;=>
     270(define (make-hash-table/sync . args)
     271  (make-object/synch (apply make-hash-table args) '(hash-table/synch:)) )
     272</enscript>
     273
     274==== define-predicate/synch
     275
     276<macro>(define-predicate/synch PREDNAME)</macro>
     277
     278<enscript language=scheme>
     279(define-predicate/synch hash-table?)
     280;=>
     281(define (hash-table?/sync obj) (object?/synch obj hash-table?))
     282</enscript>
     283
     284==== define-operation/synch
     285
     286<macro>(define-operation/synch OPERNAME)</macro>
     287
     288Note that the operand must be the first argument of {{OPERNAME}}.
     289
     290<enscript language=scheme>
     291(define-operation/synch hash-table-set!)
     292;=>
     293(define (hash-table-set!/sync mtx+obj . args)
     294  (let ((mtx (if (pair? mtx+obj) (car mtx+obj) mtx+obj)))
     295    (check-mutex+object 'hash-table-set!/synch mtx 'object/synch)
     296    (synch-with mtx+obj obj (apply hash-table-set! obj args)) ) )
     297</enscript>
    252298
    253299
     
    286332
    287333[[/man/4/Unit srfi-18|Unit srfi-18]]
     334[[/man/4/check-errors|check-errors]]
    288335
    289336
    290337== Version history
    291338
     339; 2.1.0 : Support for mutex lock/unlock arguments. Operation wrapper macros.
    292340; 2.0.0 : Port to hygienic Chicken. Removed 'set-object!/synch'.
    293341
Note: See TracChangeset for help on using the changeset viewer.