Eiffeldoc: EVENTS_SET

+

Point of view

All features

class EVENTS_SET

Summary

A set of events to be waited for. Expected events are set via the expect feature when the EVENTS_SET is not queryable. After having been waited for (see wait), the EVENTS_SET becomes queryable and events may be checked by using the event_occurred feature. To reuse the EVENTS_SET (make it not queryable again) one may call reset.

   -----------------------------                  ------------------------
  |                             | <-- wait --- |                        |
  | State: queryable          |                | State: not queryable |
  | (may call event_occurred) |                | (may call expect)    |
  |                             | -- reset --> |                        |
   -----------------------------                  ------------------------

May be useful for:

time/date waiting (see TIME_EVENTS and PERIODIC_JOB).
checking if data are available in files without locking (see INPUT_STREAM.event_can_read and OUTPUT_STREAM.event_can_write).

See also JOB

Direct parents: Insert list: ANY, PLATFORM

Overview

Creation features

make

Features

{}

make

queryable: BOOLEAN

At creation this object is not queryable.
reset

Reset the event descriptors.
wait

Blocks until requested condition (max time and/or data).
expect (event: EVENT_DESCRIPTOR)

wait will return if that event happens.
event_occurred (event: EVENT_DESCRIPTOR): BOOLEAN

True if wait returned because that event happened.

low level features

{EVENTS_SET_HANDLER}

expect_readable (descriptor: INTEGER_32)
can_read (descriptor: INTEGER_32): BOOLEAN
expect_writeable (descriptor: INTEGER_32)
can_write (descriptor: INTEGER_32): BOOLEAN
expect_exception (descriptor: INTEGER_32)
has_exception (descriptor: INTEGER_32): BOOLEAN
set_read_size (rs: INTEGER_32)
set_write_size (ws: INTEGER_32)
set_exception_size (es: INTEGER_32)
set_highest (h: INTEGER_32)

{EVENT_DESCRIPTOR}

after (timeout_ms: INTEGER_32)

timeout_ms is the max time in milliseconds to wait when wait begins.
at (date: MICROSECOND_TIME)

date is the last moment thatwait can wait.
when_data (file: INPUT_STREAM)
is_data (file: INPUT_STREAM): BOOLEAN
when_connection (server: SOCKET_SERVER)
is_connection (server: SOCKET_SERVER): BOOLEAN
when_free (file: OUTPUT_STREAM)
is_free (file: OUTPUT_STREAM): BOOLEAN
when_exception (file: STREAM)
is_exception (file: STREAM): BOOLEAN
when_expecter (expecter: EVENTS_EXPECTER)
has_expecter (expecter: EVENTS_EXPECTER): BOOLEAN

{JOB, TIME_EVENT}

current_time: MICROSECOND_TIME

Expected events

event_expected (a_event: EVENT_DESCRIPTOR): BOOLEAN

True in check modes if the event is expected.

Expected events

{}

events: FAST_ARRAY[EVENT_DESCRIPTOR]

This array is created only if the assertion level is at least require_check.
mark_event_as_expected (a_event: EVENT_DESCRIPTOR): BOOLEAN

Mark the event as expected and return True.
create_events: BOOLEAN

Create the events array.
reset_events: BOOLEAN

Empties the events array.

{}

timeout: INTEGER_32
expiration: MICROSECOND_TIME
expiration_valid: BOOLEAN
current_time_memory: MICROSECOND_TIME
current_time_valid: BOOLEAN
read_set: POINTER
read_size: INTEGER_32
read_more: BOOLEAN
write_set: POINTER
write_size: INTEGER_32
write_more: BOOLEAN
exception_set: POINTER
exception_size: INTEGER_32
exception_more: BOOLEAN
highest: INTEGER_32
sequencer_create_set: POINTER
sequencer_reset (set: POINTER)
sequencer_watch (set: POINTER, file: INTEGER_32)
sequencer_is_ready (set: POINTER, file: INTEGER_32): BOOLEAN
sequencer_wait (n: INTEGER_32, rset: POINTER, rsize: INTEGER_32, rmote: BOOLEAN, wset: POINTER, wsize: INTEGER_32, wmore: BOOLEAN, eset: POINTER, esize: INTEGER_32, emore: BOOLEAN, s: INTEGER_32, us: INTEGER_32): INTEGER_32

return -1 if signal interrupt occurred

Maximum:

{}

Maximum_character_code: INTEGER_16

Largest supported code for CHARACTER values.
Maximum_integer_8: INTEGER_8

Largest supported value of type INTEGER_8.
Maximum_integer_16: INTEGER_16

Largest supported value of type INTEGER_16.
Maximum_integer: INTEGER_32

Largest supported value of type INTEGER/INTEGER_32.
Maximum_integer_32: INTEGER_32

Largest supported value of type INTEGER/INTEGER_32.
Maximum_integer_64: INTEGER_64

Largest supported value of type INTEGER_64.
Maximum_real_32: REAL_32

Largest non-special (no NaNs nor infinity) supported value of type REAL_32.
Maximum_real: REAL_64

Largest non-special (no NaNs nor infinity) supported value of type REAL.
Maximum_real_64: REAL_64

Largest non-special (no NaNs nor infinity) supported value of type REAL.
Maximum_real_80: REAL_EXTENDED

Largest supported value of type REAL_80.

Minimum:

{}

Minimum_character_code: INTEGER_16

Smallest supported code for CHARACTER values.
Minimum_integer_8: INTEGER_8

Smallest supported value of type INTEGER_8.
Minimum_integer_16: INTEGER_16

Smallest supported value of type INTEGER_16.
Minimum_integer: INTEGER_32

Smallest supported value of type INTEGER/INTEGER_32.
Minimum_integer_32: INTEGER_32

Smallest supported value of type INTEGER/INTEGER_32.
Minimum_integer_64: INTEGER_64

Smallest supported value of type INTEGER_64.
Minimum_real_32: REAL_32

Smallest non-special (no NaNs nor infinity) supported value of type REAL_32.
Minimum_real: REAL_64

Smallest non-special (no NaNs nor infinity) supported value of type REAL.
Minimum_real_64: REAL_64

Smallest non-special (no NaNs nor infinity) supported value of type REAL.
Minimum_real_80: REAL_64

Smallest supported value of type REAL_80.

Bits:

{}

Boolean_bits: INTEGER_32

Number of bits in a value of type BOOLEAN.
Character_bits: INTEGER_32

Number of bits in a value of type CHARACTER.
Integer_bits: INTEGER_32

Number of bits in a value of type INTEGER.
Real_bits: INTEGER_32

Number of bits in a value of type REAL.
Pointer_bits: INTEGER_32

Number of bits in a value of type POINTER.

make

effective procedure

{}

require

create_events

ensure

queryable = False

queryable: BOOLEAN

writable attribute

At creation this object is not queryable.

You have to configure the conditions you want to wait for (data on file, timeout...) using expect. When the configuration is done, you start waiting using wait. Then this object is queryable, that means that you can query the state of the events, using event_occurred.

reset

effective procedure

Reset the event descriptors.

See also:

expect
wait
exception

require

reset_events

ensure

queryable = False

wait

effective procedure

Blocks until requested condition (max time and/or data).

See also:

expect
event_occurred
reset

require

not queryable

ensure

queryable

expect (event: EVENT_DESCRIPTOR)

effective procedure

wait will return if that event happens.

require

not event_expected(event)
not queryable
action: mark_event_as_expected(event)

ensure

event_expected(event)

event_occurred (event: EVENT_DESCRIPTOR): BOOLEAN

effective function

True if wait returned because that event happened.

require

event_expected(event)
queryable

expect_readable (descriptor: INTEGER_32)

effective procedure

{EVENTS_SET_HANDLER}

can_read (descriptor: INTEGER_32): BOOLEAN

effective function

{EVENTS_SET_HANDLER}

expect_writeable (descriptor: INTEGER_32)

effective procedure

{EVENTS_SET_HANDLER}

can_write (descriptor: INTEGER_32): BOOLEAN

effective function

{EVENTS_SET_HANDLER}

expect_exception (descriptor: INTEGER_32)

effective procedure

{EVENTS_SET_HANDLER}

has_exception (descriptor: INTEGER_32): BOOLEAN

effective function

{EVENTS_SET_HANDLER}

set_read_size (rs: INTEGER_32)

effective procedure

{EVENTS_SET_HANDLER}

require

rs > read_size

set_write_size (ws: INTEGER_32)

effective procedure

{EVENTS_SET_HANDLER}

require

ws > write_size

set_exception_size (es: INTEGER_32)

effective procedure

{EVENTS_SET_HANDLER}

require

es > exception_size

set_highest (h: INTEGER_32)

effective procedure

{EVENTS_SET_HANDLER}

require

h > highest

after (timeout_ms: INTEGER_32)

effective procedure

{EVENT_DESCRIPTOR}

timeout_ms is the max time in milliseconds to wait when wait begins.

require

timeout_ms >= 0
not queryable

at (date: MICROSECOND_TIME)

effective procedure

{EVENT_DESCRIPTOR}

date is the last moment thatwait can wait.

require

not queryable

when_data (file: INPUT_STREAM)

effective procedure

{EVENT_DESCRIPTOR}

require

file /= Void
file.is_connected
file.has_descriptor
not queryable

is_data (file: INPUT_STREAM): BOOLEAN

effective function

{EVENT_DESCRIPTOR}

require

file /= Void
file.is_connected
file.has_descriptor
queryable

when_connection (server: SOCKET_SERVER)

effective procedure

{EVENT_DESCRIPTOR}

require

server /= Void
not queryable

is_connection (server: SOCKET_SERVER): BOOLEAN

effective function

{EVENT_DESCRIPTOR}

require

server /= Void
queryable

when_free (file: OUTPUT_STREAM)

effective procedure

{EVENT_DESCRIPTOR}

require

file /= Void
file.is_connected
file.has_descriptor
not queryable

is_free (file: OUTPUT_STREAM): BOOLEAN

effective function

{EVENT_DESCRIPTOR}

require

file /= Void
file.is_connected
file.has_descriptor
queryable

when_exception (file: STREAM)

effective procedure

{EVENT_DESCRIPTOR}

require

file /= Void
file.is_connected
file.has_descriptor
not queryable

is_exception (file: STREAM): BOOLEAN

effective function

{EVENT_DESCRIPTOR}

require

file /= Void
file.is_connected
file.has_descriptor
queryable

when_expecter (expecter: EVENTS_EXPECTER)

effective procedure

{EVENT_DESCRIPTOR}

require

expecter /= Void
not queryable

has_expecter (expecter: EVENTS_EXPECTER): BOOLEAN

effective function

{EVENT_DESCRIPTOR}

require

expecter /= Void
queryable

current_time: MICROSECOND_TIME

effective function

{JOB, TIME_EVENT}

event_expected (a_event: EVENT_DESCRIPTOR): BOOLEAN

effective function

True in check modes if the event is expected.

Always False in boost mode. Exported to {ANY} only because the language requires it.

CAVEAT: Use only in require/ensure clauses. It's very important. In boost mode, it will always be False. It's meant to catch programming mistakes, not as a guard. If you feel the need to call that feature, please check your algorithm. Twice. And don't use it.

Tip: only call event_occurred on events that passed to expect (I mean, the same object, not a twin!)

ensure

definition: Result = events.fast_has(a_event)
equivalence: Result = a_event.expected(Current)

events: FAST_ARRAY[EVENT_DESCRIPTOR]

writable attribute

{}

This array is created only if the assertion level is at least require_check.

That's why all the functions below are used only in contracts.

mark_event_as_expected (a_event: EVENT_DESCRIPTOR): BOOLEAN

effective function

{}

Mark the event as expected and return True.

Use only in require clauses.

ensure

Result

create_events: BOOLEAN

effective function

{}

Create the events array.

Use only in require clauses.

reset_events: BOOLEAN

effective function

{}

Empties the events array.

Use only in require clauses.

timeout: INTEGER_32

writable attribute

{}

expiration: MICROSECOND_TIME

writable attribute

{}

expiration_valid: BOOLEAN

writable attribute

{}

current_time_memory: MICROSECOND_TIME

writable attribute

{}

current_time_valid: BOOLEAN

writable attribute

{}

read_set: POINTER

writable attribute

{}

read_size: INTEGER_32

writable attribute

{}

read_more: BOOLEAN

writable attribute

{}

write_set: POINTER

writable attribute

{}

write_size: INTEGER_32

writable attribute

{}

write_more: BOOLEAN

writable attribute

{}

exception_set: POINTER

writable attribute

{}

exception_size: INTEGER_32

writable attribute

{}

exception_more: BOOLEAN

writable attribute

{}

highest: INTEGER_32

writable attribute

{}

sequencer_create_set: POINTER

{}

sequencer_reset (set: POINTER)

{}

sequencer_watch (set: POINTER, file: INTEGER_32)

{}

sequencer_is_ready (set: POINTER, file: INTEGER_32): BOOLEAN

{}

sequencer_wait (n: INTEGER_32, rset: POINTER, rsize: INTEGER_32, rmote: BOOLEAN, wset: POINTER, wsize: INTEGER_32, wmore: BOOLEAN, eset: POINTER, esize: INTEGER_32, emore: BOOLEAN, s: INTEGER_32, us: INTEGER_32): INTEGER_32

{}

return -1 if signal interrupt occurred

Maximum_character_code: INTEGER_16

{}

Largest supported code for CHARACTER values.

ensure

meaningful: Result >= 127

Maximum_integer_8: INTEGER_8

is 127

constant attribute

{}

Largest supported value of type INTEGER_8.

Maximum_integer_16: INTEGER_16

is 32767

constant attribute

{}

Largest supported value of type INTEGER_16.

Maximum_integer: INTEGER_32

is 2147483647

constant attribute

{}

Largest supported value of type INTEGER/INTEGER_32.

Maximum_integer_32: INTEGER_32

is 2147483647

constant attribute

{}

Largest supported value of type INTEGER/INTEGER_32.

Maximum_integer_64: INTEGER_64

is 9223372036854775807

constant attribute

{}

Largest supported value of type INTEGER_64.

Maximum_real_32: REAL_32

is {REAL_32 3.4028234663852885981170418348451692544e+38}

constant attribute

{}

Largest non-special (no NaNs nor infinity) supported value of type REAL_32.

Maximum_real: REAL_64

{}

Largest non-special (no NaNs nor infinity) supported value of type REAL.

Just to give an idea of this value: 1.79769313486231570....e+308

Maximum_real_64: REAL_64

{}

Largest non-special (no NaNs nor infinity) supported value of type REAL.

Just to give an idea of this value: 1.79769313486231570....e+308

Maximum_real_80: REAL_EXTENDED

{}

Largest supported value of type REAL_80.

ensure

meaningful: Result >= Maximum_real

Minimum_character_code: INTEGER_16

{}

Smallest supported code for CHARACTER values.

ensure

meaningful: Result <= 0

Minimum_integer_8: INTEGER_8

is -128

constant attribute

{}

Smallest supported value of type INTEGER_8.

Minimum_integer_16: INTEGER_16

is -32768

constant attribute

{}

Smallest supported value of type INTEGER_16.

Minimum_integer: INTEGER_32

is -2147483648

constant attribute

{}

Smallest supported value of type INTEGER/INTEGER_32.

Minimum_integer_32: INTEGER_32

is -2147483648

constant attribute

{}

Smallest supported value of type INTEGER/INTEGER_32.

Minimum_integer_64: INTEGER_64

is -9223372036854775808

constant attribute

{}

Smallest supported value of type INTEGER_64.

Minimum_real_32: REAL_32

is {REAL_32 -3.40282346638528859811704183484516925440e+38}

constant attribute

{}

Smallest non-special (no NaNs nor infinity) supported value of type REAL_32.

Minimum_real: REAL_64

{}

Smallest non-special (no NaNs nor infinity) supported value of type REAL.

Just to give an idea of this value: -1.79769313486231570....e+308

Minimum_real_64: REAL_64

{}

Smallest non-special (no NaNs nor infinity) supported value of type REAL.

Just to give an idea of this value: -1.79769313486231570....e+308

Minimum_real_80: REAL_64

{}

Smallest supported value of type REAL_80.

ensure

meaningful: Result <= 0.0

Boolean_bits: INTEGER_32

{}

Number of bits in a value of type BOOLEAN.

ensure

meaningful: Result >= 1

Character_bits: INTEGER_32

{}

Number of bits in a value of type CHARACTER.

ensure

meaningful: Result >= 1
large_enough: {INTEGER_32 2} ^ Result >= Maximum_character_code

Integer_bits: INTEGER_32

{}

Number of bits in a value of type INTEGER.

ensure

integer_definition: Result = 32

Real_bits: INTEGER_32

is 64

constant attribute

{}

Number of bits in a value of type REAL.

Pointer_bits: INTEGER_32

{}

Number of bits in a value of type POINTER.