
events_defer

   Defer event handling

Type
   Event Handling

Description
    	Defer event handling until a subsequent call to events_nodefer/0.
	The purpose of this feature is to
	
	    sequence event handlers so they don't interrupt each other
	    protect accesses to global data structures from being interrupted
		or preempted by events.
	
	Events whose handling will be deferred are:
	
	    events raised by the builtin event/1
	    events posted from external code using ec_post_event()
	    events raised by interrupts whose handler is event/1
	
	Events that are raised while event handling is deferred will be
	queued and handled later.
    
	Event handling is also automatically deferred when entering the
	event handlers of events that have the defer-property set (see
	event_create/3 and set_event_handler/2).
    
    	The predicate fails (and has no further effect) if event handling
	is already deferred. This feature should be used to make sure that
	event handling is not accidentally reenabled in a nested situation.
	E.g.
	
	    ...,
	    ( events_defer ->
	        <manipulate protected data>
		events_nodefer
	    ;
		% events already deferred
	        <manipulate protected data>
	    ),
	    ...
	

    
	CAUTION: events_defer/0 is a low-level primitive that must be
	used with great care. Part of ECLiPSe's functionality (e.g. timeout,
	branch-and-bound) relies on event handling and will not work
	properly while event handling is deferred. Deferring and undeferring
	events are nonlogical operations which are not undone on backtracking.
	The programmer must therefore make sure that every time event handling
	is deferred, it is eventually reenabled by a call to events_nodefer/0,
	even in case of failure or abort in the deferred code sequence.
    
    

Modes and Determinism
   events_defer is semidet

Fail Conditions
   Fails iff event handling is already deferred

Examples
       ?- event_create(writeln(hello), [], E),
	    event(E),
	    writeln(deferring),
	    events_defer,
	    event(E),
	    writeln(nodeferring),
	    events_nodefer.
    hello
    deferring
    nodeferring
    hello
    

See Also
   event_create / 3, event / 1, events_nodefer / 0, set_event_handler / 2
