First published on MSDN on Mar 29, 2010
Hi,
In this series of blog posts we will help you to design, develop and debug the Resource DLL you are developing to give your application high-availability with Windows Server 2008 & 2008 R2 Failover Clustering.
We recommend you start with the other blog post in the series:
Now that we’ve described which components are involved, and how they interact, let’s see what the resource state machine looks like from the point of view of RHS.
RHS interacts to the Resource DLL using the Resource DLL entry points. You can find detailed information about them on MSDN:
http://msdn.microsoft.com/en-us/library/aa372244(VS.85).aspx
The list below shows all the entry points that a resource DLL is expected to implement. Think of this as a mapping between common cluster operations, and how they specifically interact with this new resource type. After the Resource DLL is loaded, RHS will call Startup to provide to the Resource DLL pointers to some of its functions, and to get from the Resource DLL pointers to the resource’s functions.
- Close removes a resource instance from the cluster
- IsAlive determines if a resource is actually operational
- LooksAlive determines if a resource appears to be available for use
- Offline performs a graceful shutdown of the resource
- Online starts the resource and makes it available to the cluster
- Open creates a new resource instance
- ResourceControl supports resource control codes
- ResourceTypeControl supports resource type control codes
- Startup receives the LogEvent and SetResourceStatus callbacks and returns a function table
- Terminate performs an immediate shutdown of the resource
Please note that ResourceControl and ResourceTypeControl are optional. If user does not provide them, it only means this resource and resource type will not have private properties.
Open is called to notify the Resource DLL that a new instance of this resource has been created. After Open was called, the Resource DLL should be ready to receive ResourceTypeControls . Close is called to notify the Resource DLL that the resource instance is being deleted.
At this point the Resource DLL and RHS are set up to start handling resources. For every resource that will be handled in the context of the given RHS process, the appropriate Resource DLL will get an Open call. In the Open call the Resource DLL should allocate the context to keep information about this instance of the resource. If Open completes successfully, then the resource is in the Opened state, Offline sub-state.
When cluster stops RCM and RHS will make sure to bring the resource to offline state, and to call Close for that resource so the Resource DLL can perform clean-up before it re- Open it in the new monitor.
In this post we will not discuss the calls that are related to the arbitration of the quorum resources – Arbitrate, and Release. Instead we will concentrate on the calls Online , Offline , Terminate , IsAlive , LooksAlive and ResourceControl.
From the RHS perspective, while in the opened state, a resource can be in the Offline, Onlining, Online or Offlining sub-states. Onlining and Offlining have sub-states, and resource will be in one of the sub-states. Transitions to the states are performed as RHS makes calls to the Resource DLL, and based on the calls results. Please remember that in this post we are talking about states in the RHS. RHS states are internal to the cluster implementation, and are not exposed to the user using UI or APIs. RHS states are different from RCM states, and you can see the RCM states from the UI or programmatic interfaces, such as “offline”.
We can split the calls into several categories based on how RHS and Resource DLL handles them.
- Online and Offline are more complicated because they have a concept of being in “pending” state, and the way RHS handles timeouts of these calls is different
- ResourceControl can be sent to the resource in any sub-states of the Opened state
- Terminate can be issued concurrently with any other call, except Open and Close
- LooksAlive and IsAlive can be sent to the resource only while they are Online
Below you can see a state chart diagram that shows RHS Resource state machine. I would like to stress that this is the RHS’s state machine. The Resource DLL state machine might be based on this state machine, but might have some other sub-states specific for the application. To interpret this diagram, you need to be aware that this is a hierarchical state machine diagraph, also known as a UML State Machine, as described here: http://en.wikipedia.org/wiki/UML_state_machine.
In the next post in this series we will walk through several scenarios using the above state diagram.
Thanks,
Vladimir Petter
Senior Software Development Engineer
Clustering & High-Availability
Microsoft