Changeset 37024 in project


Ignore:
Timestamp:
12/24/18 21:14:26 (8 months ago)
Author:
Kon Lovett
Message:

rel 3.2.0

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/eggref/5/synch

    r36935 r37024  
    2121</enscript>
    2222
    23 === Synchronized Invocation - Continuation Safe
    24 
    25 These forms have the mutex lock/unlock wrapped in '''{{dynamic-wind}}'''.
     23Synch wraps the user code with some form of ''isolation''. The implementation
     24forms are split into 4 modules:
     25
     26; {{synch-open}} : no attempted ''isolation''
     27; {{synch-dyn}} : {{dynamic-wind}}
     28; {{synch-exn}} : {{handle-exceptions}}
     29; {{synch-dynexn}} : both
     30
     31The default module exports {{synch-open}}, {{synch-params}}, & {{synch-dyn}}.
     32
     33=== Parameters
     34
     35Used by {{synch-dyn}}, {{synch-exn}}, & {{synch-dynexn}}.
     36
     37==== Usage
     38
     39<enscript language=scheme>
     40(import synch-params)
     41</enscript>
     42
     43==== current-synch-exit-condition
     44
     45<parameter>(current-synch-exit-condition [OBJ])</parameter>
     46
     47Object to designate premature exit of synchronized body due to exit
     48continuation.
     49
     50Default is {{'synch-exit}}.
     51
     52==== current-synch-raise
     53
     54<parameter>(current-synch-raise [PROC/1])</parameter>
     55
     56Procedure of one argument to call when premature exit of synchronized body due
     57to exception.
     58
     59Default is {{synch-raise-warning}}.
     60
     61==== current-synch-abandon?
     62
     63<parameter>(current-synch-abandon? [BOOL])</parameter>
     64
     65Premature exit of synchronized body leaves mutex abandoned?
     66
     67Default is {{#f}}.
     68
     69Conceptually how closely bound is the synchronizing mutex to what is being
     70synchronized; is the mutex state part of the error state? The presumption is
     71not, but there are other scenarios.
     72
     73==== synch-raise-warning
     74
     75<procedure>(current-synch-raise OBJ)</procedure>
     76
     77Uses {{warning}} to announce receipt of {{OBJ}}, but does not ''raise'' the
     78exception.
     79
     80=== Synchronized Invocation (exit continuation aware)
     81
     82Some protection. Assumes no exception raised by the synchronized expression.
     83
     84==== Usage
     85
     86<enscript language=scheme>
     87(import synch-dyn)
     88</enscript>
    2689
    2790==== synch
     
    82145<syntax>(synch-lock MUTEX-FORM [BODY ...]) -> *</syntax>
    83146
    84 Execute {{BODY ...}} while {{MUTEX}} locked, and leave mutex locked.
     147Executes {{BODY ...}} while {{MUTEX}} locked, and leaves mutex locked,
     148assuming the {{BODY ...}} does not invoke an exit continuation.
    85149
    86150Returns the result of {{BODY ...}}.
     
    90154<syntax>(synch-unlock MUTEX-FORM [BODY ...]) -> *</syntax>
    91155
    92 Execute {{BODY ...}} while {{MUTEX}} locked, and leave mutex unlocked.
    93 
    94 Returns the result of {{BODY ...}}.
    95 
    96 Should the mutex be unlocked a warning is issued and the mutex is locked before
    97 executing the {{BODY}}.
     156Executes {{BODY ...}} while {{MUTEX}} locked, and leaves mutex unlocked.
     157
     158Returns the result of {{BODY ...}}.
     159
     160Should the mutex be unlocked an error is issued.
    98161
    99162==== let-synch-with
     
    174237{{RECORD-SYMBOL}} and {{RECORD-OBJECT}} are per '''{{record-synch}}'''.
    175238
    176 Should the mutex be unlocked a warning is issued and the mutex is locked before
    177 executing the {{BODY}}.
    178 
    179 === Synchronized Invocation - Continuation Unsafe
    180 
    181 These forms do not have the mutex lock/unlock wrapped in '''{{dynamic-wind}}''',
    182 otherwise the same behavior.
    183 
    184 ==== %call-synch
    185 
    186 <syntax>(%call-synch MUTEX-FORM PROCEDURE [ARGUMENTS ...]) -> *</syntax>
    187 
    188 ==== %call-synch-with
    189 
    190 <syntax>(%call-synch-with MUTEX-FORM PROCEDURE [ARGUMENTS ...]) -> *</syntax>
    191 
    192 ==== %apply-synch
    193 
    194 <syntax>(%apply-synch MUTEX-FORM PROCEDURE [ARGUMENTS ...]) -> *</syntax>
    195 
    196 ==== %apply-synch-with
    197 
    198 <syntax>(%apply-synch-with MUTEX-FORM PROCEDURE [ARGUMENTS ...]) -> *</syntax>
    199 
    200 ==== %synch
    201 
    202 <syntax>(%synch MUTEX-FORM [BODY ...]) -> *</syntax>
    203 
    204 ==== %synch-with
    205 
    206 <syntax>(%synch-with MUTEX-FORM VARIABLE [BODY ...]) -> *</syntax>
    207 
    208 ==== %synch-lock
    209 
    210 <syntax>(%synch-lock MUTEX-FORM [BODY ...]) -> *</syntax>
    211 
    212 ==== %synch-unlock
    213 
    214 <syntax>(%synch-unlock MUTEX-FORM [BODY ...]) -> *</syntax>
    215 
    216 ==== %let-synch
    217 
    218 <syntax>(%let-synch BINDINGS [BODY ...]) -> *</syntax>
    219 
    220 ==== %set!-synch-with
    221 
    222 <syntax>(%set!-synch-with MUTEX-FORM VARIABLE [BODY ...]) -> *</syntax>
    223 
    224 ==== %object-synch-cut-with
    225 
    226 <syntax>(%object-synch-cut-with MUTEX-FORM [BODY ...]) -> *</syntax>
    227 
    228 ==== %record-synch
    229 
    230 <syntax>(%record-synch RECORD-OBJECT RECORD-SYMBOL [BODY ...]) -> *</syntax>
    231 
    232 ==== %record-synch-lock
    233 
    234 <syntax>(%record-synch-lock RECORD-OBJECT RECORD-SYMBOL [BODY ...]) -> *</syntax>
    235 
    236 ==== %record-synch-unlock
    237 
    238 <syntax>(%record-synch-unlock RECORD-OBJECT RECORD-SYMBOL [BODY ...]) -> *</syntax>
     239Should the mutex be unlocked an error is issued.
    239240
    240241=== Object Synchronization
     
    300301</enscript>
    301302
     303==== synchronized-procedure
     304
     305<procedure>(synchronized-procedure PROC) -> procedure</procedure>
     306
     307Returns a synchronized version of {{PROC}}
     308
     309=== Synchronized Invocation (exception aware)
     310
     311More protection, but expensive. Provides the same API as {{synch-dyn)}}.
     312
     313==== Usage
     314
     315<enscript language=scheme>
     316(import synch-exn)
     317</enscript>
     318
     319==== synch
     320==== synch-with
     321==== call-synch
     322==== call-synch-with
     323==== apply-synch
     324==== apply-synch-with
     325==== synch-lock
     326==== synch-unlock
     327==== let-synch-with
     328==== set!-synch-with
     329
     330==== object-synch-cut-with
     331==== record-synch
     332==== record-synch-lock
     333==== record-synch-unlock
     334
     335==== synch-with-object?
     336==== define-constructor-synch
     337==== define-predicate-synch
     338==== define-operation-synch
     339
     340==== synchronized-procedure
     341
     342=== Synchronized Invocation (exit continuation & exception aware)
     343
     344More protection, but expensive. Provides the same API as {{synch-dyn)}}.
     345
     346==== Usage
     347
     348<enscript language=scheme>
     349(import synch-dynexn)
     350</enscript>
     351
     352==== synch
     353==== synch-with
     354==== call-synch
     355==== call-synch-with
     356==== apply-synch
     357==== apply-synch-with
     358==== synch-lock
     359==== synch-unlock
     360==== let-synch-with
     361==== set!-synch-with
     362
     363==== object-synch-cut-with
     364==== record-synch
     365==== record-synch-lock
     366==== record-synch-unlock
     367
     368==== synch-with-object?
     369==== define-constructor-synch
     370==== define-predicate-synch
     371==== define-operation-synch
     372
     373==== synchronized-procedure
     374
     375=== Synchronized Invocation (exit continuation unaware)
     376
     377No protection. Assumes no exit continuation called or exception raised by the
     378synchronized expression.
     379
     380==== Usage
     381
     382Also available as:
     383
     384<enscript language=scheme>
     385(import synch-open)
     386</enscript>
     387
     388==== %call-synch
     389
     390<syntax>(%call-synch MUTEX-FORM PROCEDURE [ARGUMENTS ...]) -> *</syntax>
     391
     392==== %call-synch-with
     393
     394<syntax>(%call-synch-with MUTEX-FORM PROCEDURE [ARGUMENTS ...]) -> *</syntax>
     395
     396==== %apply-synch
     397
     398<syntax>(%apply-synch MUTEX-FORM PROCEDURE [ARGUMENTS ...]) -> *</syntax>
     399
     400==== %apply-synch-with
     401
     402<syntax>(%apply-synch-with MUTEX-FORM PROCEDURE [ARGUMENTS ...]) -> *</syntax>
     403
     404==== %synch
     405
     406<syntax>(%synch MUTEX-FORM [BODY ...]) -> *</syntax>
     407
     408==== %synch-with
     409
     410<syntax>(%synch-with MUTEX-FORM VARIABLE [BODY ...]) -> *</syntax>
     411
     412==== %synch-lock
     413
     414<syntax>(%synch-lock MUTEX-FORM [BODY ...]) -> *</syntax>
     415
     416==== %synch-unlock
     417
     418<syntax>(%synch-unlock MUTEX-FORM [BODY ...]) -> *</syntax>
     419
     420==== %let-synch
     421
     422<syntax>(%let-synch BINDINGS [BODY ...]) -> *</syntax>
     423
     424==== %set!-synch-with
     425
     426<syntax>(%set!-synch-with MUTEX-FORM VARIABLE [BODY ...]) -> *</syntax>
     427
     428==== %object-synch-cut-with
     429
     430<syntax>(%object-synch-cut-with MUTEX-FORM [BODY ...]) -> *</syntax>
     431
     432==== %record-synch
     433
     434<syntax>(%record-synch RECORD-OBJECT RECORD-SYMBOL [BODY ...]) -> *</syntax>
     435
     436==== %record-synch-lock
     437
     438<syntax>(%record-synch-lock RECORD-OBJECT RECORD-SYMBOL [BODY ...]) -> *</syntax>
     439
     440==== %record-synch-unlock
     441
     442<syntax>(%record-synch-unlock RECORD-OBJECT RECORD-SYMBOL [BODY ...]) -> *</syntax>
     443
    302444==== define-operation-%synch
    303445
     
    306448Note that the operand must be the first argument of {{OPERNAME}}.
    307449
    308 ==== synchronized-procedure
    309 
    310 <procedure>(synchronized-procedure PROC) -> procedure</procedure>
    311 
    312 Returns a synchronized version of {{PROC}}
     450'''Bug''': part of ''Object Synchronization'' & useless without the rest,
     451available only thru one of the other {{synch-*}} modules.
     452
     453
     454== Bugs & Limitations
     455
     456* {{define-*-synch}} is obtuse.
    313457
    314458
     
    317461* Inspired by Thomas Chust.
    318462
    319 
    320 == Bugs & Limitations
    321 
    322 * {{define-*-synch}} is obtuse.
     463* Thanks to Jörg Wittenberger.
    323464
    324465
     
    330471== Requirements
    331472
    332 [[/man/4/Unit srfi-18|Unit srfi-18]]
    333 [[/man/4/check-errors|check-errors]]
     473[[srfi-18]]
     474[[check-errors]]
    334475
    335476
    336477== Version history
    337478
    338 ; 3.1.0 : Remove {{critical-region}} malarkey.
     479; 3.2.0 : Fix lock failure handling. Add modules {{synch-dyn}}, {{synch-exn}}, {{synch-dynexn}}, {{synch-open}}.
     480; 3.1.0 :
    339481; 3.0.0 : CHICKEN 5 release.
    340482; 2.3.0 : Add {{critical-region}}, {{synchronized-procedure}}, {{record-synch}}, {{record-synch-lock}}, {{record-synch-unlock}}, {{call-synch}}, {{call-synch-with}}, {{apply-synch}}, {{apply-synch-with}}, {{let-synch-with}}, {{set!-synch-with}}, {{synch-lock}}, {{synch-unlock}}, {{object-synch-cut-with}}, {{make-synch-with-object}}, {{synch-with-object?}}, {{define-constructor-synch}}, {{define-predicate-synch}}, {{define-operation-synch}}.
Note: See TracChangeset for help on using the changeset viewer.