net.ranides.assira.events
Class EventLock

java.lang.Object
  net.ranides.assira.events.EventLock

Direct Known Subclasses:

EventLockQue, EventLockUnsafe

public abstract class EventLock
extends Object

Klasa pozwalająca na synchroniczną obsługę zdarzeń. Pozwala wstrzymać wykonanie bieżącego wątku i oczekiwać, aż do wskazanego EventRouter'a dotrze zdarzenie określonego typu.

Zależnie od rodzaju implementacji, klasa może oferować usługi o różnym stopniu dokładności i bezpieczeństwa.

Najsilniejsze gwarancje, to możliwość obsługi wszystkich zdarzeń określonego rodzaju bez ryzyka pominięcia żadnego. Nawet jeśli jedno lub więcej zdarzeń nastąpiło przed (lub pomiędzy) wywołaniem metody waitForEvent(), to zostanie ono dostarczone. Gwarantowana jest również prawidłowa kolejność dostarczenia komunikatów przez kolejne wywołania metod blokujących. Implementacje "silne" mają duże wymagania pamięciowe, w ekstremalnym przypadku mogą spowodować przepełnienie sterty, jeśli program zostanie zalany komunikatami.

"Słaby EventLock" daje gwarancje, że metody waitForEvent() nie będą blokować, jeśli pomiędzy ich wywołaniami (albo przed wywołaniem) wystąpiło obserwowane zdarzenie. Nie dają jednak gwarancji dostarczenia wszystkich komunikatów - część z nich może być utracona/pominięta, w przypadku wysokiego obciążenia. Słaby EventLock udostępnia informację o ilości zgubionych komunikatów. Jego zaletą jest znacznie mniejsze zużycie pamięci oraz brak podatności na przeciążenie aplikacji.

"Niebezpieczny EventLock" nie oferuje żadnych gwarancji. Co więcej: metody waitForEvent() zawsze blokują, a jako wynik zwracają tylko i wyłącznie wydarzenie, które nastąpiło w czasie blokady. Z tego powodu jest silnie podatny na race condition. Jego zaletą jest niemal całkowity brak obciążenia pamięci oraz procesora. Z tego powodu może być z powodzeniem używany do obserwacji zdarzeń przychodzących w bardzo dużo odstępach (względem czasu obsługi) bez obaw o wydajność aplikacji.

Author:

ranides

Constructor Summary

EventLock()

Method Summary

static EventLockQue	lock(Class<? extends Event> event, EventRouter router) Metoda tworzy silny EventLock - szczegóły "silnego kontraktu" są w opisie klasy EventLock).
abstract void	release() Niszczy obiekt EventLock i zwalnia wszystkie zasoby.
abstract void	reset() Resetuje stan obiektu - jeśli EventLock przechowywał w kolejce nieobsłużone zdarzenia - są one usuwane.
static EventLock	singleLock(Class<? extends Event> event, EventRouter router) Metoda tworzy silny EventLock, który może zostać wykorzystany tylko raz - szczegóły "słabego kontraktu" są w opisie klasy EventLock).
static EventLock	unsafeLock(Class<? extends Event> event, EventRouter router) Metoda tworzy niebezpieczny EventLock - szczegóły "niebezpiecznego kontraktu" są w opisie klasy EventLock).
abstract Event	waitForEvent() Metoda blokująca: wstrzymuje wykonanie bieżącego wątku do momentu, aż do obserwowanego EventRouter'a dotrze dowolne zdarzenie oczekiwane przez EventLock lub wystąpi wyjątek InterruptedException.
abstract <T extends Event> T	waitForEvent(Class<T> event) Wersja oczekująca na zdarzenie konkretnego rodzaju.
abstract <T extends Event> T	waitForEvent(Class<T> event, long timeout) Wersja oczekująca na zdarzenie konkretnego rodzaju.
abstract Event	waitForEvent(long timeout) Metoda blokująca: wstrzymuje wykonanie bieżącego wątku do momentu, aż do obserwowanego EventRouter'a dotrze dowolne zdarzenie oczekiwane przez EventLock, wystąpi wyjątek InterruptedException, lub minie podany czas.
static EventLockQue	weakLock(Class<? extends Event> event, EventRouter router, int capacity) Metoda tworzy silny EventLock - szczegóły "słabego kontraktu" są w opisie klasy EventLock).

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

EventLock

public EventLock()

Method Detail

release

public abstract void release()

Niszczy obiekt EventLock i zwalnia wszystkie zasoby.

reset

public abstract void reset()

Resetuje stan obiektu - jeśli EventLock przechowywał w kolejce nieobsłużone zdarzenia - są one usuwane. Wywołanie funkcji reset pomiędzy dwoma wywołaniami metody wait może spowodować, że część zdarzeń, którymi EventLock był zainteresowany zostanie utracona.

waitForEvent

public abstract Event waitForEvent()
                            throws InterruptedException

Metoda blokująca: wstrzymuje wykonanie bieżącego wątku do momentu, aż do obserwowanego EventRouter'a dotrze dowolne zdarzenie oczekiwane przez EventLock lub wystąpi wyjątek InterruptedException. Zobacz opis klasy EventLock aby poznać szczegóły.

Returns:

oczekiwane zdarzenie

Throws:

InterruptedException

waitForEvent

public abstract Event waitForEvent(long timeout)
                            throws InterruptedException

Metoda blokująca: wstrzymuje wykonanie bieżącego wątku do momentu, aż do obserwowanego EventRouter'a dotrze dowolne zdarzenie oczekiwane przez EventLock, wystąpi wyjątek InterruptedException, lub minie podany czas. Zobacz opis klasy EventLock aby poznać szczegóły.

Parameters:

timeout -

Returns:

oczekiwane zdarzenie

Throws:

InterruptedException

waitForEvent

public abstract <T extends Event> T waitForEvent(Class<T> event)
                                      throws InterruptedException

Wersja oczekująca na zdarzenie konkretnego rodzaju. Zachowuje się identycznie jak waitForEvent(), z tą różnicą, że reaguje na mniejszy zakres zdarzeń - zawężony tylko do podanej klasy oraz jej pochodnych.

Metoda przydatna szczególnie wtedy, gdy utworzony obiekt EventLock reaguje na bardzo ogólną klasę zdarzeń, a użytkownik w danym momencie chce wstrzymać wykonanie w oczekiwaniu na zdarzenie bardziej szczegółowe.

Type Parameters:

T -

Parameters:

event -

Returns:

oczekiwane zdarzenie lub null, jeśli minął timeout

Throws:

InterruptedException

waitForEvent

public abstract <T extends Event> T waitForEvent(Class<T> event,
                                                 long timeout)
                                      throws InterruptedException

Wersja oczekująca na zdarzenie konkretnego rodzaju. Zachowuje się identycznie jak waitForEvent(long timeout), z tą różnicą, że reaguje na mniejszy zakres zdarzeń - zawężony tylko do podanej klasy oraz jej pochodnych.

Metoda przydatna szczególnie wtedy, gdy utworzony obiekt EventLock reaguje na bardzo ogólną klasę zdarzeń, a użytkownik w danym momencie chce wstrzymać wykonanie w oczekiwaniu na zdarzenie bardziej szczegółowe.

Type Parameters:

T -

Parameters:

event -

timeout -

Returns:

oczekiwane zdarzenie lub null, jeśli minął timeout

Throws:

InterruptedException

lock

public static EventLockQue lock(Class<? extends Event> event,
                                EventRouter router)

Metoda tworzy silny EventLock - szczegóły "silnego kontraktu" są w opisie klasy EventLock).

Jeśli obiekt nie jest już potrzebny, musi zostać zwolniony za pomocą metody release()

Parameters:

event -

router -

Returns:

weakLock

public static EventLockQue weakLock(Class<? extends Event> event,
                                    EventRouter router,
                                    int capacity)

Metoda tworzy silny EventLock - szczegóły "słabego kontraktu" są w opisie klasy EventLock).

Jeśli obiekt nie jest już potrzebny, musi zostać zwolniony za pomocą metody release()

Parameters:

event -

router -

capacity -

Returns:

singleLock

public static EventLock singleLock(Class<? extends Event> event,
                                   EventRouter router)

Metoda tworzy silny EventLock, który może zostać wykorzystany tylko raz - szczegóły "słabego kontraktu" są w opisie klasy EventLock).

Po wywołaniu zakończeniu metody waitForEvent obiekt sam automatycznie zwalnia wszystkie zasoby i przestaje być funcjonalny.

Parameters:

event -

router -

Returns:

unsafeLock

@Meta.Unsafe
public static EventLock unsafeLock(Class<? extends Event> event,
                                               EventRouter router)

Metoda tworzy niebezpieczny EventLock - szczegóły "niebezpiecznego kontraktu" są w opisie klasy EventLock).

Jeśli obiekt nie jest już potrzebny, musi zostać zwolniony za pomocą metody release()

Parameters:

event -

router -

Returns: