Apache Derby Database Engine and Embedded JDBC Driver 10.17.1.0 · org.apache.derby.impl.services.daemon.BasicDaemon

A BasicDaemon is a background worker thread which does asynchronous I/O and general clean up. It should not be used as a general worker thread for parallel execution. One cannot count on the order of request or count on when the daemon will wake up, even with serviceNow requests. Request are not persistent and not recoverable, they are all lost when the system crashes or is shutdown. System shutdown, even orderly ones, do not wait for daemons to finish its work or empty its queue. Furthermore, any Serviceable subscriptions, including onDemandOnly, must tolerate spurious services. The BasicDaemon will setup a context manager with no context on it. The Serviceable object's performWork must provide useful context on the context manager to do its work. The BasicDaemon will wrap performWork call with try / catch block and will use the ContextManager's error handling to clean up any error. The BasicDaemon will guarentee serviceNow request will not be lost as long as the jbms does not crash - however, if N serviceNow requests are made by the same client, it may only be serviced once, not N times. Many Serviceable object will subscribe to the same BasicDaemon. Their performWork method should be well behaved - in other words, it should not take too long or hog too many resources or deadlock with anyone else. And it cannot (should not) error out. The BasicDaemon implementation manages the DaemonService's data structure, handles subscriptions and enqueues requests, and determine the service schedule for its Serviceable objects. The BasicDaemon keeps an array (Vector) of Serviceable subscriptions it also keeps 2 queues for clients that uses it for one time service - the 1st queue is for a serviceNow enqueue request, the 2nd queue is for non serviceNow enqueue request. This BasicDaemon services its clients in the following order: 1. any subscribed client that have made a serviceNow request that has not been fulfilled 2. serviceable clients on the 1st queue 3. all subscribed clients that are not onDemandOnly 4. serviceable clients 2nd queue

Field Summary

Modifier and Type	Field and Description
private boolean	awakened
protected final ContextManager	contextMgr
protected final ContextService	contextService
private int	earlyWakeupCount
private final List<ServiceRecord>	highPQ Queues for the work to be done.
private boolean	inPause
private long	lastServiceTime
private int	nextService which subscribed clients to service next?
private final List<ServiceRecord>	normPQ
private int	numClients
private static final int	OPTIMAL_QUEUE_SIZE
private boolean	running
private boolean	stopped
private boolean	stopRequested
private final Vector<ServiceRecord>	subscription
private boolean	waiting true if I'm waiting, if this is false then I am running and a notify is not required.

Constructor Summary

Access	Constructor and Description
public	BasicDaemon(ContextService contextService) make a BasicDaemon

Method Summary

Modifier and Type	Method and Description
public synchronized void	clear() Implements org.apache.derby.iapi.services.daemon.DaemonService.clear. Get rid of all queued up Serviceable tasks.
public boolean	enqueue(Serviceable the object that needs a one time service newClient, boolean if true, this client should be serviced ASAP, as if a serviceNow has been issued. If false, then this client will be serviced with the normal scheduled. serviceNow) Implements org.apache.derby.iapi.services.daemon.DaemonService.enqueue. Request a one time service from the Daemon.
pack-priv static ModuleFactory	getMonitor() Must be package private so that user code can't call this entry point.
private synchronized boolean	inPause()
protected ServiceRecord	nextAssignment(boolean urgent)
public void	pause() Implements org.apache.derby.iapi.services.daemon.DaemonService.pause. Pause.
private boolean	rest() Returns true if awakened by some notification, false if wake up by timer
public void	resume() Implements org.apache.derby.iapi.services.daemon.DaemonService.resume. Resume service after a pause
public void	run() Implements java.lang.Runnable.run. Runs this operation.
protected void	serviceClient(ServiceRecord clientRecord)
public void	serviceNow(int the number that uniquely identifies the client clientNumber) Implements org.apache.derby.iapi.services.daemon.DaemonService.serviceNow. Service this subscription ASAP.
private static void	setThreadPriority(ModuleFactory mf, final int priority) Change the priority of the current thread, but only if it was created by `ModuleFactory#getDaemonThread`.
public void	stop() Implements org.apache.derby.iapi.services.daemon.DaemonService.stop. Finish what we are doing and at the next convenient moment, get rid of the thread and make the daemon object goes away if possible.
private synchronized boolean	stopRequested()
public int	subscribe(Serviceable a Serviceable object this daemon will service from time to time newClient, boolean only service this client when it ask for service with a serviceNow request onDemandOnly) Implements org.apache.derby.iapi.services.daemon.DaemonService.subscribe. Add a new client that this daemon needs to service
public void	unsubscribe(int client identifier clientNumber) Implements org.apache.derby.iapi.services.daemon.DaemonService.unsubscribe. Removes a client from the list of subscribed clients.
public void	waitUntilQueueIsEmpty() Implements org.apache.derby.iapi.services.daemon.DaemonService.waitUntilQueueIsEmpty.
protected synchronized void	wakeUp()
private void	work(boolean urgentOnly)
private void	yieldNow()

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

awakened	back to summary
private boolean awakened

contextMgr	back to summary
protected final ContextManager contextMgr

contextService	back to summary
protected final ContextService contextService

earlyWakeupCount	back to summary
private int earlyWakeupCount

highPQ	back to summary
private final List<ServiceRecord> highPQ Queues for the work to be done. These are synchronized by this object.

inPause	back to summary
private boolean inPause

lastServiceTime	back to summary
private long lastServiceTime

nextService	back to summary
private int nextService which subscribed clients to service next? only accessed by daemon thread

normPQ	back to summary
private final List<ServiceRecord> normPQ

numClients	back to summary
private int numClients

OPTIMAL_QUEUE_SIZE	back to summary
private static final int OPTIMAL_QUEUE_SIZE

running	back to summary
private boolean running

stopped	back to summary
private boolean stopped

stopRequested	back to summary
private boolean stopRequested

subscription	back to summary
private final Vector<ServiceRecord> subscription

waiting	back to summary
private boolean waiting true if I'm waiting, if this is false then I am running and a notify is not required.

Constructor Detail

BasicDaemon	back to summary
public BasicDaemon(ContextService contextService) make a BasicDaemon

Method Detail

clear	back to summary
public synchronized void clear() Implements org.apache.derby.iapi.services.daemon.DaemonService.clear. Get rid of all queued up Serviceable tasks.

clear

back to summary

public synchronized void clear()

Implements org.apache.derby.iapi.services.daemon.DaemonService.clear.

Get rid of all queued up Serviceable tasks.

enqueue	back to summary
public boolean enqueue(Serviceable newClient, boolean serviceNow) Implements org.apache.derby.iapi.services.daemon.DaemonService.enqueue. Doc from org.apache.derby.iapi.services.daemon.DaemonService.enqueue. Request a one time service from the Daemon. Unless performWork returns REQUEUE (see Serviceable), the daemon will service this client once and then it will get rid of this client. Since no client number is associated with this client, it cannot request to be serviced or be unsubscribed. The work is always added to the deamon, regardless of the state it returns. Parameters newClient:Serviceable the object that needs a one time service serviceNow:boolean if true, this client should be serviced ASAP, as if a serviceNow has been issued. If false, then this client will be serviced with the normal scheduled. Returns:boolean true if the daemon indicates it is being overloaded, false it's happy.

enqueue

back to summary

public boolean enqueue(Serviceable newClient, boolean serviceNow)

Implements org.apache.derby.iapi.services.daemon.DaemonService.enqueue.

Doc from org.apache.derby.iapi.services.daemon.DaemonService.enqueue.

Request a one time service from the Daemon. Unless performWork returns REQUEUE (see Serviceable), the daemon will service this client once and then it will get rid of this client. Since no client number is associated with this client, it cannot request to be serviced or be unsubscribed. The work is always added to the deamon, regardless of the state it returns.

Parameters

newClient:Serviceable: the object that needs a one time service
serviceNow:boolean: if true, this client should be serviced ASAP, as if a serviceNow has been issued. If false, then this client will be serviced with the normal scheduled.

Returns:boolean

true if the daemon indicates it is being overloaded, false it's happy.

getMonitor	back to summary
pack-priv static ModuleFactory getMonitor() Must be package private so that user code can't call this entry point.

inPause	back to summary
private synchronized boolean inPause()

nextAssignment	back to summary
protected ServiceRecord nextAssignment(boolean urgent)

pause	back to summary
public void pause() Implements org.apache.derby.iapi.services.daemon.DaemonService.pause. Doc from org.apache.derby.iapi.services.daemon.DaemonService.pause. Pause. No new service is performed until a resume is issued.

pause

back to summary

public void pause()

Implements org.apache.derby.iapi.services.daemon.DaemonService.pause.

Doc from org.apache.derby.iapi.services.daemon.DaemonService.pause.

Pause. No new service is performed until a resume is issued.

rest	back to summary
private boolean rest() Returns true if awakened by some notification, false if wake up by timer

resume	back to summary
public void resume() Implements org.apache.derby.iapi.services.daemon.DaemonService.resume. Doc from org.apache.derby.iapi.services.daemon.DaemonService.resume. Resume service after a pause

resume

back to summary

public void resume()

Implements org.apache.derby.iapi.services.daemon.DaemonService.resume.

Doc from org.apache.derby.iapi.services.daemon.DaemonService.resume.

Resume service after a pause

run	back to summary
public void run() Implements java.lang.Runnable.run. Doc from java.lang.Runnable.run. Runs this operation.

run

back to summary

public void run()

Implements java.lang.Runnable.run.

Doc from java.lang.Runnable.run.

Runs this operation.

serviceClient	back to summary
protected void serviceClient(ServiceRecord clientRecord)

serviceNow back to summary

serviceNow	back to summary
public void serviceNow(int clientNumber) Implements org.apache.derby.iapi.services.daemon.DaemonService.serviceNow. Doc from org.apache.derby.iapi.services.daemon.DaemonService.serviceNow. Service this subscription ASAP. When this method is called, the subscriber's `performWork()` method is guaranteed to be invoked at some point in the future. However, there is no guarantee that a subscriber's `performWork()` is called the same number of times as the subscriber calls this method. More precisely, if a subscriber is waiting for this daemon service to invoke its `performWork()` method, the daemon service may, but is not required to, ignore requests from that subscriber until the `performWork()` method has been invoked. Parameters clientNumber:int the number that uniquely identifies the client

public void serviceNow(int clientNumber)

Implements org.apache.derby.iapi.services.daemon.DaemonService.serviceNow.

Doc from org.apache.derby.iapi.services.daemon.DaemonService.serviceNow.

Service this subscription ASAP. When this method is called, the subscriber's performWork() method is guaranteed to be invoked at some point in the future. However, there is no guarantee that a subscriber's performWork() is called the same number of times as the subscriber calls this method. More precisely, if a subscriber is waiting for this daemon service to invoke its performWork() method, the daemon service may, but is not required to, ignore requests from that subscriber until the performWork() method has been invoked.

Parameters

clientNumber:int: the number that uniquely identifies the client

setThreadPriority	back to summary
private static void setThreadPriority(ModuleFactory mf, final int priority) Change the priority of the current thread, but only if it was created by `ModuleFactory#getDaemonThread`.

stop	back to summary
public void stop() Implements org.apache.derby.iapi.services.daemon.DaemonService.stop. Finish what we are doing and at the next convenient moment, get rid of the thread and make the daemon object goes away if possible. remember we are calling from another thread

stop

back to summary

public void stop()

Implements org.apache.derby.iapi.services.daemon.DaemonService.stop.

Finish what we are doing and at the next convenient moment, get rid of the thread and make the daemon object goes away if possible. remember we are calling from another thread

stopRequested	back to summary
private synchronized boolean stopRequested()

subscribe	back to summary
public int subscribe(Serviceable newClient, boolean onDemandOnly) Implements org.apache.derby.iapi.services.daemon.DaemonService.subscribe. Doc from org.apache.derby.iapi.services.daemon.DaemonService.subscribe. Add a new client that this daemon needs to service Parameters newClient:Serviceable a Serviceable object this daemon will service from time to time onDemandOnly:boolean only service this client when it ask for service with a serviceNow request Returns:int a client number that uniquely identifies this client (this subscription)

back to summary

public int subscribe(Serviceable newClient, boolean onDemandOnly)

Implements org.apache.derby.iapi.services.daemon.DaemonService.subscribe.

Doc from org.apache.derby.iapi.services.daemon.DaemonService.subscribe.

Add a new client that this daemon needs to service

Parameters

newClient:Serviceable: a Serviceable object this daemon will service from time to time
onDemandOnly:boolean: only service this client when it ask for service with a serviceNow request

Returns:int

a client number that uniquely identifies this client (this subscription)

unsubscribe back to summary

unsubscribe	back to summary
public void unsubscribe(int clientNumber) Implements org.apache.derby.iapi.services.daemon.DaemonService.unsubscribe. Removes a client from the list of subscribed clients. The call does not wait for the daemon to finish the work it is currently performing. Therefore, the client must tolerate that its `performWork()` method could be invoked even after the call to `unsubscribe()` has returned (but not more than once). Parameters clientNumber:int client identifier

public void unsubscribe(int clientNumber)

Implements org.apache.derby.iapi.services.daemon.DaemonService.unsubscribe.

Removes a client from the list of subscribed clients. The call does not wait for the daemon to finish the work it is currently performing. Therefore, the client must tolerate that its performWork() method could be invoked even after the call to unsubscribe() has returned (but not more than once).

Parameters

clientNumber:int: client identifier

waitUntilQueueIsEmpty	back to summary
public void waitUntilQueueIsEmpty() Implements org.apache.derby.iapi.services.daemon.DaemonService.waitUntilQueueIsEmpty.

wakeUp	back to summary
protected synchronized void wakeUp()

work	back to summary
private void work(boolean urgentOnly)

yieldNow	back to summary
private void yieldNow()

public Class BasicDaemon

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail