Preface

The ChorusOS 4.0 Hot Restart Programmer's Guide provides information for developers of high-availability applications that use the ChorusOS(TM) 4.0 hot restart feature and associated API. Hot restart provides a means of reducing the time it takes to restart an application or entire system when a serious failure occurs, based on the use of persistent memory. This guide provides a high-level overview of the hot restart architecture, and then looks in detail at how the hot restart API is used.

Who Should Use This Book

Use this book if you need to develop ChorusOS 4.0 actors that can be rapidly restarted in the event of failure, or if you need to use persistent memory in your applications. You will also find the first chapter useful if you are simply interested in learning what hot restart is and what it can do.

Before You Read This Book

If you are simply interested in learning what hot restart is, you will need to be familiar with C programming, and with the high-level architecture of the ChorusOS system before reading this guide. If you will be developing applications with hot restart, you are also expected to be familiar with programming ChorusOS actors, and the Sun Embedded WorkShop(TM) development tools. All of the ChorusOS prerequisite topics are covered in the ChorusOS 4.0 Introduction.

You will need access to a working ChorusOS host machine and target platform if you want to run the hot restart demonstration and example programs.

How This Book Is Organized

This book is divided into four chapters and two appendixes that present different aspects of the hot restart feature.

• Chapter 1, Introduction provides a general introduction to what hot restart is and does, and how it is incorporated in the ChorusOS 4.0 system architecture.

• Chapter 2, Getting Started With Hot Restart is a step-by-step guide to getting up and running with hot restart, from configuring the system to running the hot restart demonstration application.

• Chapter 3, Programming With Persistent Memory takes an in-depth look at how the persistent memory API provided by hot restart can be used. The persistent memory API can be used by any ChorusOS actor.

• Chapter 4, Programming With Restartable Actors describes the API used for developing restartable actors, and explains how the hot restart mechanism works from a programming point of view.

• Appendix A, Hot Restart Programming Environment provides information of use to developers for compiling actors that use the hot restart API.

• Appendix B, Example Application Code lists the code of the examples used in the body of this guide.

Related Books

The following documents contain information that is related to the material covered in this guide:

• The ChorusOS 4.0 Introduction comprises a basic overview and getting started guide for new users of the ChorusOS 4.0 system. Familiarity with the information in the ChorusOS 4.0 Introduction is a prerequisite for users of this Programmer's Guide.

• The ChorusOS 4.0 Installation Guide, ChorusOS Target Family Guides and related documents cover installation and configuration of the ChorusOS 4.0 system and the Sun Embedded Workshop development tools.

• For a complete reference to the APIs available in the ChorusOS 4.0 system, see the man pages in the ChorusOS 4.0 Reference Manual Collection. The 2RESTART section in this collection covers the API exported by the hot restart feature. Other related man pages are also referenced in the body of this Programmer's Guide.

Ordering Sun Documents

Fatbrain.com, an Internet professional bookstore, stocks selected product documentation from Sun Microsystems, Inc.

For a list of documents and how to order them, visit the Sun Documentation Center on Fatbrain.com at http://www1.fatbrain.com/documentation/sun.

Accessing Sun Documentation Online

The docs.sun.com^SM Web site enables you to access Sun technical documentation online. You can browse the docs.sun.com archive or search for a specific book title or subject. The URL is http://www.oracle.com/technetwork/indexes/documentation/index.html.

Typographic Conventions

The following table describes the typographic changes used in this book.

Table P-1 Typographic Conventions

Typeface or Symbol	Meaning	Example
AaBbCc123	The names of commands, files, and directories; on-screen computer output	Edit your .login file. Use ls -a to list all files. machine_name% you have mail.
AaBbCc123	What you type, contrasted with on-screen computer output	machine_name% su Password:
AaBbCc123	Command-line placeholder: replace with a real name or value	To delete a file, type rm filename.
AaBbCc123	Book titles, new words, or terms, or words to be emphasized.	Read Chapter 6 in User's Guide. These are called class options. You must be root to do this.

Shell Prompts

The following table shows the default system prompt and superuser prompt for the C shell, Bourne shell, and Korn shell.

Table P-2 Shell Prompts

Shell	Prompt
C shell prompt	machine_name%
C shell superuser prompt	machine_name#
Bourne shell and Korn shell prompt	$
Bourne shell and Korn shell superuser prompt	#

Directory Conventions

The following table describes several of the directory conventions used in this book.

Table P-3 Directory Conventions

Name	Meaning	Example
install_dir	Directory into which you install the ChorusOS 4.0 product.	/opt/SUNWconn/SEW
build_dir	Directory in which you build your ChorusOS system image from the installed product.	/home/user/ChorusOS