orca.shirako.kernel
Class Kernel

java.lang.Object
  orca.shirako.kernel.Kernel

All Implemented Interfaces:

IKernel

public class Kernel
extends java.lang.Object
implements IKernel

The "kernel" of the slices core: one Manager object exists for each locally instantiated actor, and it handles the synchronized internals of all operations on the actor, after argument validation/prepare steps in KernelWrapper.

This is a generic resource manager suitable for use in any slices server: authority, agent/broker, or service manager. The resource manager maintains a collection of slices, each of which has a set of Reservations; each Reservation has a set of assigned resources (e.g., nodes). The manager initiates asynchronous setup and teardown on reservations, monitors reservation status, and queues completions for reservation state changes. Resource state may change out from under us, so the manager frequently probes and refreshes its cached state.

The manager plugs in under the generic server/actor. In general, public methods in this module are called from SlicesActor. This manager class does not distinguish between client and server, since they maintain identical data structures at the manager level. The different contexts use different implementations for the Reservation class, concrete resource sets, (underneath generic ResourceSet), and a SlicesPlugin to manage underlying reservation and slice state (e.g., for Cluster-on-Demand or a database layer).

The current server implementations synchronize through synchronized methods on this class. All state changes hold a lock on the Manager. All data structures in the slices package are protected by this lock. Objects passed in are from the parser and must be checked against the current (locked) state. Errors propagate as exceptions suitable for returning to the client. This module is semi-atomic: client errors do not corrupt manager state. Note: "service" operations on Reservations are unlocked for concurrency.

Constructor Summary

Kernel(IShirakoPlugin plugin, IPolicy mapper, LoggingTool logger)
Creates a new kernel instance.

Method Summary

protected void	amendReserve(ResourceReservation reservation) Amends a previous reserve operation (both client and server side) for the reservation.
protected void	claim(BrokerReservation reservation) Processes a requests to claim new ticket for previously exported resources (broker role).
protected void	close(ResourceReservation reservation) Handles a close operation for the reservation.
protected int	compareAndUpdate(ReservationClient incoming, ReservationClient current, boolean ticket) Compares the sequence numbers of both reservations.
protected int	compareAndUpdate(ReservationServer incoming, ReservationServer current) Compares the incoming request to the corresponding reservation stored at this actor.
protected int	compareAndUpdateIgnorePending(ReservationServer incoming, ReservationServer current) Similar to compareAndUpdate but will update the reservation even if there is a pending operation currently in progress.
protected void	extendLease(ResourceReservation reservation) Handles an extend lease operation for the reservation.
protected int	extendReservation(ReservationID rid, ResourceSet rset, Term term) Extends the reservation with the given resources and term.
protected int	extendReservation(ResourceReservation reservation, ResourceSet resources, Term term) Extends the reservation with the given resources and term.
protected void	extendTicket(ResourceReservation reservation) Handles an extend ticket operation for the reservation.
Slice[]	getClientSlices() Returns all client slices registered with the kernel.
Slice[]	getInventorySlices() Returns all inventory slices registered with the kernel.
protected Slice	getLocalSlice(Slice slice) Returns the slice object registered with the kernel that corresponds to the argument.
protected Slice	getOrCreateLocalSlice(AuthToken identity, ResourceReservation reservation, boolean createNewSlice) Returns the slice specified in the reservation or creates a new slice with the given parameters.
ResourceReservation	getReservation(ReservationID rid) Returns the reservation with the given reservation identifier.
ResourceReservation[]	getReservations(SliceID sliceID) Returns all reservations in the given slice
Slice	getSlice(SliceID sliceID) Returns the slice with the given name.
Slice[]	getSlices() Returns all slice registered with the kernel.
IShirakoPlugin	getSlicesPlugin() Returns the Shirako plugin.
protected void	handleDuplicateRequest(ResourceReservation current, int operation)
protected void	notify(int id, IReservation r) Raises the specified event
protected void	probePending(ResourceReservation reservation) Probes to check for completion of pending operation.
protected void	redeem(ReservationClient reservation) Issues a redeem for a new ticket in Service Manager role.
void	registerReservation(ResourceReservation reservation) Registers the given reservation with the kernel.
void	registerSlice(Slice slice) Registers the slice with the kernel: adds the slice object to the kernel data structures and adds a database record for the slice.
void	removeReservation(ReservationID rid) Unregisters the reservation from the kernel data structures and removes its record from the database.
void	removeSlice(SliceID sliceID) Unregisters the slice (if it is registered with the kernel) and removes it from the database.
void	reregisterReservation(ResourceReservation reservation) Registers a previously unregistered reservation with the kernel.
void	reregisterSlice(Slice slice) Registers the slice with the kernel: adds the slice object to the kernel data structures.
protected void	reserve(ResourceReservation reservation) Handles a reserve operation for the reservation.
protected ResourceReservation	softValidate(ReservationID rid) Retrieves the locally registered reservation that corresponds to the passed reservation.
protected ResourceReservation	softValidate(ResourceReservation r) Retrieves the locally registered reservation that corresponds to the passed reservation.
void	tick() Checks all reservations for completions or problems.
void	unregisterReservation(ReservationID rid) Unregisters the reservation from the kernel data structures.
void	unregisterSlice(SliceID sliceID) Unregisters the slice and releases any resources that it may hold.
protected void	updateLease(ResourceReservation reservation, ResourceReservation update, UpdateData udd) Handles an incoming update lease operation (client side only).
protected void	updateTicket(ReservationClient reservation, ResourceReservation update, UpdateData udd) Handles an incoming update ticket operation (client side only).
protected ResourceReservation	validate(ReservationID rid) Retrieves the locally registered reservation that corresponds to the passed reservation.
protected ResourceReservation	validate(ResourceReservation reservation) Retrieves the locally registered reservation that corresponds to the passed reservation.

Methods inherited from class java.lang.Object

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

Constructor Detail

Kernel

public Kernel(IShirakoPlugin plugin,
              IPolicy mapper,
              LoggingTool logger)

Creates a new kernel instance.

Parameters:

plugin - Shirako plugin instance

mapper - policy

logger - logger

Method Detail

registerSlice

public void registerSlice(Slice slice)
                   throws java.lang.Exception

Description copied from interface: IKernel

Registers the slice with the kernel: adds the slice object to the kernel data structures and adds a database record for the slice.

Specified by:

registerSlice in interface IKernel

Parameters:

slice - slice to register

Throws:

java.lang.Exception - if the slice is already registered or a database error occurs. If a database error occurs, the slice will be unregistered.

reregisterSlice

public void reregisterSlice(Slice slice)
                     throws java.lang.Exception

Description copied from interface: IKernel

Registers the slice with the kernel: adds the slice object to the kernel data structures. The slice object must have an existing database record.

Specified by:

reregisterSlice in interface IKernel

Parameters:

slice - slice to register

Throws:

java.lang.Exception - if the slice is already registered or a database error occurs. If a database error occurs, the slice will be unregistered.

unregisterSlice

public void unregisterSlice(SliceID sliceID)
                     throws java.lang.Exception

Description copied from interface: IKernel

Unregisters the slice and releases any resources that it may hold.

Note: A slice can be unregistered only if it contains only closed or failed reservations.

Specified by:

unregisterSlice in interface IKernel

Parameters:

sliceID - identifier of slice to unregister

Throws:

java.lang.Exception

removeSlice

public void removeSlice(SliceID sliceID)
                 throws java.lang.Exception

Description copied from interface: IKernel

Unregisters the slice (if it is registered with the kernel) and removes it from the database.

Note: A slice can be removed only if it contains only closed or failed reservations.

Specified by:

removeSlice in interface IKernel

Parameters:

sliceID - identifier of slice to remove

Throws:

java.lang.Exception

getSlice

public Slice getSlice(SliceID sliceID)

Description copied from interface: IKernel

Returns the slice with the given name.

Specified by:

getSlice in interface IKernel

Parameters:

sliceID - identifier of slice to return

Returns:

the requested slice or null if no slice with the requested name is registered with the kernel.

getLocalSlice

protected Slice getLocalSlice(Slice slice)
                       throws java.lang.Exception

Returns the slice object registered with the kernel that corresponds to the argument.

Parameters:

slice - incoming slice object

Returns:

the locally registered slice object

Throws:

java.lang.IllegalArgumentException - if the arguments are invalid

java.lang.Exception - if no locally registered slice object exists

getOrCreateLocalSlice

protected Slice getOrCreateLocalSlice(AuthToken identity,
                                      ResourceReservation reservation,
                                      boolean createNewSlice)
                               throws java.lang.Exception

Returns the slice specified in the reservation or creates a new slice with the given parameters. Newly created slices are registered with the kernel.

Parameters:

identity - actor identity

name - slice name

resourceData - slice parameters

agentClient - true if this slice represents an broker acting as a client

other - additional parameters

Returns:

the slice object

Throws:

java.lang.Exception

getSlices

public Slice[] getSlices()

Description copied from interface: IKernel

Returns all slice registered with the kernel.

Specified by:

getSlices in interface IKernel

Returns:

an array of slices registered with the kernel

getInventorySlices

public Slice[] getInventorySlices()

Description copied from interface: IKernel

Returns all inventory slices registered with the kernel.

Specified by:

getInventorySlices in interface IKernel

Returns:

an array of inventory slices registered with the kernel

getClientSlices

public Slice[] getClientSlices()

Description copied from interface: IKernel

Returns all client slices registered with the kernel.

Specified by:

getClientSlices in interface IKernel

Returns:

an array of client slices registered with the kernel

registerReservation

public void registerReservation(ResourceReservation reservation)
                         throws java.lang.Exception

Description copied from interface: IKernel

Registers the given reservation with the kernel. Adds a database record for the reservation. The containing slice should have been previously registered with the kernel and no database record should exist. When registering a reservation with an existing database record use IKernel.reregisterReservation(ResourceReservation). Only reservations that are not closed or failed can be registered. Closed or failed reservations will be ignored.

Specified by:

registerReservation in interface IKernel

Parameters:

reservation - the reservation to register

Throws:

java.lang.IllegalArgumentException - when the passed in argument is illegal

java.lang.Exception - if the reservation has already been registered with the kernel.

java.lang.RuntimeException - when a database error occurs. In this case the reservation will be unregistered from the kernel data structures.

reregisterReservation

public void reregisterReservation(ResourceReservation reservation)
                           throws java.lang.Exception

Description copied from interface: IKernel

Registers a previously unregistered reservation with the kernel. The containing slice should have been previously registered with the kernel and a database record for the reservation should exist. When registering a reservation without and existing database record use IKernel.registerReservation(ResourceReservation). Only reservations that are not closed or failed can be registered. Closed or failed reservations will be ignored.

Specified by:

reregisterReservation in interface IKernel

Parameters:

reservation - the reservation to reregister

Throws:

java.lang.IllegalArgumentException - when the passed in argument is illegal

java.lang.Exception - if the reservation has already been registered with the kernel or the reservation does not have a database record. In the latter case the reservation will be unregistered from the kernel data structures.

java.lang.RuntimeException - if a database error occurs

unregisterReservation

public void unregisterReservation(ReservationID rid)
                           throws java.lang.Exception

Description copied from interface: IKernel

Unregisters the reservation from the kernel data structures.

Note: does not remove the reservation database record.

*

Note:Only failed, closed, or close waiting reservations can be unregistered.

Specified by:

unregisterReservation in interface IKernel

Parameters:

rid - identifier for reservation to unregister

Throws:

java.lang.IllegalArgumentException - when the passed in argument is illegal

java.lang.Exception

getReservation

public ResourceReservation getReservation(ReservationID rid)

Description copied from interface: IKernel

Returns the reservation with the given reservation identifier.

Specified by:

getReservation in interface IKernel

Parameters:

rid - reservation identifier

Returns:

reservation with the given reservation identifier

getReservations

public ResourceReservation[] getReservations(SliceID sliceID)

Description copied from interface: IKernel

Returns all reservations in the given slice

Specified by:

getReservations in interface IKernel

Parameters:

sliceID - identifier of slice

Returns:

an array of all reservations in the slice

validate

protected ResourceReservation validate(ResourceReservation reservation)
                                throws java.lang.Exception

Retrieves the locally registered reservation that corresponds to the passed reservation. Obtains the reservation from the containing slice object.

Parameters:

reservation - reservation being validated

Returns:

the locally registered reservation that corresponds to the passed reservation

Throws:

java.lang.Exception - if there is no local reservation that corresponds to the passed reservation

validate

protected ResourceReservation validate(ReservationID rid)
                                throws java.lang.Exception

Retrieves the locally registered reservation that corresponds to the passed reservation. Does not obtain the reservation from the containing slice object.

Parameters:

rid - reservation identifier of reservation being validated

Returns:

the locally registered reservation that corresponds to the passed reservation

Throws:

java.lang.Exception - if there is no local reservation that corresponds to the passed reservation

softValidate

protected ResourceReservation softValidate(ResourceReservation r)
                                    throws java.lang.Exception

Retrieves the locally registered reservation that corresponds to the passed reservation. Obtains the reservation from the containing slice object.

Parameters:

reservation - reservation being validated

Returns:

the locally registered reservation that corresponds to the passed reservation or null if no local reservation exists

Throws:

java.lang.IllegalArgumentException - if the arguments are invalid

java.lang.Exception - if the slice referenced by the incoming reservation is not locally registered

softValidate

protected ResourceReservation softValidate(ReservationID rid)
                                    throws java.lang.Exception

Retrieves the locally registered reservation that corresponds to the passed reservation. Does not obtain the reservation from the containing slice object.

Parameters:

rid - reservation identifier or reservation being validated

Returns:

the locally registered reservation that corresponds to the passed reservation or null if no local reservation exists

Throws:

java.lang.IllegalArgumentException - if the arguments are invalid

java.lang.Exception

removeReservation

public void removeReservation(ReservationID rid)
                       throws java.lang.Exception

Description copied from interface: IKernel

Unregisters the reservation from the kernel data structures and removes its record from the database.

Note:Only failed, closed, or close waiting reservations can be removed.

Specified by:

removeReservation in interface IKernel

Parameters:

rid - identifier of reservation to remove

Throws:

java.lang.Exception

extendReservation

protected int extendReservation(ResourceReservation reservation,
                                ResourceSet resources,
                                Term term)
                         throws java.lang.Exception

Extends the reservation with the given resources and term.

Parameters:

reservation - reservation to extend

resources - resources to use for the extension

term - term to use for the extension

Returns:

0 if the reservation extension operation can be initiated, ImageManagerConstants.ReservationHasPendingOperation if the reservation has a pending operation, which prevents the extend operation from being initiated.

Throws:

java.lang.Exception

extendReservation

protected int extendReservation(ReservationID rid,
                                ResourceSet rset,
                                Term term)
                         throws java.lang.Exception

Extends the reservation with the given resources and term.

Parameters:

reservation - reservation identifier of reservation to extend

resources - resources to use for the extension

term - term to use for the extension

Returns:

0 if the reservation extension operation can be initiated, ImageManagerConstants.ReservationHasPendingOperation if the reservation has a pending operation, which prevents the extend operation from being initiated.

Throws:

java.lang.Exception

reserve

protected void reserve(ResourceReservation reservation)
                throws java.lang.Exception

Handles a reserve operation for the reservation.

Client: issue a ticket request or a claim request.

Broker: process a request for a new ticket. Claims for previously exported tickets are handled by claim(BrokerReservation).

Authority: process a request for a new lease.

Parameters:

reservation - reservation for which to perform redeem

Throws:

java.lang.Exception

amendReserve

protected void amendReserve(ResourceReservation reservation)
                     throws java.lang.Exception

Amends a previous reserve operation (both client and server side) for the reservation.

Parameters:

reservation - the reservation

Throws:

java.lang.Exception

See Also:

reserve(ResourceReservation)

redeem

protected void redeem(ReservationClient reservation)
               throws java.lang.Exception

Issues a redeem for a new ticket in Service Manager role. On the server (authority) side this request comes comes in as a reserve().

Parameters:

reservation - reservation being redeemed

Throws:

java.lang.Exception

claim

protected void claim(BrokerReservation reservation)
              throws java.lang.Exception

Processes a requests to claim new ticket for previously exported resources (broker role). On the client side this request is issued by reserve(ResourceReservation).

Parameters:

reservation - the reservation being claimed

Throws:

java.lang.Exception

extendTicket

protected void extendTicket(ResourceReservation reservation)
                     throws java.lang.Exception

Handles an extend ticket operation for the reservation.

Client: issue an extend ticket request.

Broker: process a request for a ticket extension.

Parameters:

reservation - reservation for which to perform extend ticket

Throws:

java.lang.Exception

extendLease

protected void extendLease(ResourceReservation reservation)
                    throws java.lang.Exception

Handles an extend lease operation for the reservation.

Client: issue an extend lease request.

Authority: process a request for a lease extension.

Parameters:

reservation - reservation for which to perform extend lease

Throws:

java.lang.Exception

close

protected void close(ResourceReservation reservation)
              throws java.lang.Exception

Handles a close operation for the reservation.

Client: perform local close operations and issue close request to authority.

Broker: perform local close operations

Authority: process a close request

Parameters:

reservation - reservation for which to perform close

Throws:

java.lang.Exception

updateTicket

protected void updateTicket(ReservationClient reservation,
                            ResourceReservation update,
                            UpdateData udd)
                     throws java.lang.Exception

Handles an incoming update ticket operation (client side only).

Parameters:

reservation - local reservation

update - update sent from upstream broker

udd - status of the operation the broker is informing us about

Throws:

java.lang.Exception

updateLease

protected void updateLease(ResourceReservation reservation,
                           ResourceReservation update,
                           UpdateData udd)
                    throws java.lang.Exception

Handles an incoming update lease operation (client side only).

Parameters:

reservation - local reservation

update - update sent from site authority

udd - status of the operation the authority is informing us about

Throws:

java.lang.Exception

probePending

protected void probePending(ResourceReservation reservation)
                     throws java.lang.Exception

Probes to check for completion of pending operation.

Parameters:

reservation - the reservation being probed

Throws:

java.lang.Exception - rare

notify

protected void notify(int id,
                      IReservation r)
               throws java.lang.Exception

Raises the specified event

Parameters:

id - event id

r - reservation this event is associated with

Throws:

java.lang.Exception

tick

public void tick()
          throws java.lang.Exception

Description copied from interface: IKernel

Checks all reservations for completions or problems. We might want to do these a few at a time.

Specified by:

tick in interface IKernel

Throws:

java.lang.Exception

compareAndUpdate

protected int compareAndUpdate(ReservationClient incoming,
                               ReservationClient current,
                               boolean ticket)

Compares the sequence numbers of both reservations. Returns: SequenceSmaller if (incoming < current) SequenceEqual if (incoming = current) SequenceGreater if (incoming > current) If the result is SequenceGreater, updates the sequence number of current to the one of incoming

compareAndUpdate

protected int compareAndUpdate(ReservationServer incoming,
                               ReservationServer current)

Compares the incoming request to the corresponding reservation stored at this actor. First compares sequence numbers. If the incoming request has a larger sequence number and there is no pending operation for this reservation, we update the sequence number of the current reservation and set the requestedTerm and requestedResources fields. This is a locked method!

Parameters:

incoming - the incoming request

current - the corresponding reservation stored at the server

Returns:

a comparison status flag (see Sequence*)

compareAndUpdateIgnorePending

protected int compareAndUpdateIgnorePending(ReservationServer incoming,
                                            ReservationServer current)

Similar to compareAndUpdate but will update the reservation even if there is a pending operation currently in progress. Use with caution.

Parameters:

incoming - the incoming request

current - the corresponding reservation stored at the server

Returns:

a comparison status flag (see Sequence*)

See Also:

compareAndUpdate(ReservationServer, ReservationServer)

handleDuplicateRequest

protected void handleDuplicateRequest(ResourceReservation current,
                                      int operation)
                               throws java.lang.Exception

Throws:

java.lang.Exception

getSlicesPlugin

public IShirakoPlugin getSlicesPlugin()

Description copied from interface: IKernel

Returns the Shirako plugin.

Specified by:

getSlicesPlugin in interface IKernel

Returns:

Shirako plugin