hrfexecl(2RESTART)

NAME | SYNOPSIS | API RESTRICTIONS | FEATURES | DESCRIPTION | LIMITATIONS | RETURN VALUES | ERRORS | ATTRIBUTES | SEE ALSO

NAME

hrfexec, hrfexecl, hrfexecv, hrfexecle, hrfexecve, hrfexeclp, hrfexecvp- spawn a hot restartable actor

SYNOPSIS

#include <hr/hr.h>

int hrfexecl(PmmName * baseName, const char * path, KnCap * cactorcap, const AcParam * param, const char * arg0, (...), const char * argn, char * /* NULL */);
int hrfexecv(PmmName * baseName, const char * path, KnCap * cactorcap, const AcParam * param, char *const * argv);
int hrfexecle(PmmName * baseName, const char * path, KnCap * cactorcap, const AcParam * param, const char * arg0, (...), const char * argn, char * /* NULL */, char const * envp);
int hrfexecve(PmmName * baseName, const char * path, KnCap * cactorcap, const AcParam * param, char const * argv, char const * envp);
int hrfexeclp(PmmName * baseName, const char * file, KnCap * cactorcap, const AcParam * param, const char * arg0, (...), const char * argn, char * /* NULL */);
int hrfexecvp(PmmName * baseName, const char * file, KnCap * cactorcap, const AcParam * param, char *const * argv);

API RESTRICTIONS

The function or functions documented here may not be used safely in all application contexts with all APIs provided in the ChorusOS 5.0 product.

See API(5FEA) for details.

FEATURES

HOT_RESTART

DESCRIPTION

The functions in the hrfexec() function family are used to spawn hot restartable actors. hrfexec() functions can only be called by a hot restartable actor. hrfexec() functions provide support for initially loading an actor image (text and data) into persistent memory, and for restarting the actor from this image after a restart. The spawned hot restartable actor is registered and run as a member of the same restart group as the calling actor.

hrfexec() functions accept the same parameters as afexec(2K) functions, with the addition of the baseName parameter.

The baseName parameter is a PmmName structure with two fields, medium and name , as described in the man page for pmmAllocate(2RESTART) . The medium field must be set to RAM . The name field is used to register and uniquely identify the spawned hot restartable actor in the Hot Restart Controller. The actor will only be unregistered when the actor's group terminates, or disappears from persistent memory (system reboot). It is the programmer's responsibility to ensure that each hot restartable actor registered with the Hot Restart Controller uses a unique name, as name clashes at run time are not detected by the system, and will cause unpredictable behavior.

When an hrfexec() function is called, the Hot Restart Controller checks whether baseName->name identifies an actor which is already registered.

If the actor is not already registered, the Hot Restart Controller does the following:

• Registers the actor with the specified name as a member of the invoking actor's restart group.

• Solicits the Persistent Memory Manager to allocate space in persistent memory for the initialized actor image, and the executed image. The actor image occupies a single persistent memory block containing the actor's text and initialized data. The executed image occupies two persistent memory blocks: one block containing the executed code, and another block containing the initialized data and BSS. Persistent memory blocks used to store an actor's actor image and executing image will only be freed when the actor's restart group terminates cleanly.

• Creates, loads and starts the actor in the space allocated, using acreate(2K) , aload(2K) and astart(2K) . A set of pre-open stdin / stdout / stderr is specified by the invoker of hrfexec() using an AcParam structure, which is interpreted in the same way as for afexec() . See acreate(2K) for a description of the AcParam structure.

If the name is already registered, the Hot Restart Controller determines that the actor needs to be restarted. It ignores the file and param arguments passed to hrfexec() and re-loads the executed image from the actor image backed-up in persistent memory. The actor is started with a capacity and actor ID which may be different to the capacity and actor ID of previous run-time instances of the actor. The run-time (relocated) code and data of a hot restartable actor are always loaded at the same address. The new start is similar to the initial one, that is, the standard runtime startup routine (usually _start() ) is called. This routine calls the program's main() function.

When a restart occurs, actors launched by hrfexec() in the affected group(s) stop executing but are not restarted automatically. Only actors launched with the C_INIT command arun(1M) with the -g option are restarted by the system. These actors are then responsible for restarting other hot restartable actors by re-invoking hrfexec() .

Clean Termination of Spawned Actors

Actors spawned with an hrfexec() function must terminate cleanly, using the macro HR_EXIT_HDL(2RESTART) followed by exit(3STDC) , as described in the man page for HR_EXIT_HDL(2RESTART) . A restartable actor group can only terminate cleanly when every actor that has been run in the group since the group's creation has terminated cleanly. This includes actors spawned by hrfexec() that may not have been restarted after a group restart. This is possible when an actor is spawned subject to a condition that changes after a restart. The spawned actor is registered as a member of the restart group, but will not be able to terminate cleanly as it will not be respawned by its parent after the restart. As a result, the group will not be able to terminate cleanly.

Because of this behavior, care must be taken to ensure that all actors spawned with hrfexec() are given a chance to terminate cleanly, for example by implementing a clean-up actor to restart any blocked spawned actors before group termination. This is described in the ChorusOS 4.0 Hot Restart Programmer's Guide .

LIMITATIONS

gzip -compressed executables cannot be used as restartable actors, even if the GZ_FILE feature is set. Attempting to pass a gzip -compressed file to an hrfexec() function will result in an ENOEXEC error.

Dynam ic libraries cannot be used with restartable actors. Attempting to run a dynamically-linked actor as a restartable actor will result in an ENOEXEC error.

The Hot Restart Controller does not detect name sharing between two distinct actors. It is the programmer's responsibility to ensure that two distinct actors registered in the Hot Restart Controller do not use the same name.

RETURN VALUES

If successful, hrfexec() functions return a non-negative integer that is the actor ID of the new hot restartable actor. Otherwise, hrfexec() functions return -1 and set errno to indicate one of the following error conditions.

ERRORS

[E2BIG]

The number of bytes used by the new actor image's argument list and environment list is greater than ARG_MAX bytes.

[EACCES]

The invoking actor is not hot restartable.

Attempt to spawn an actor which is registered in a restart group different to the restart group of the invoking actor.

[EFAULT]

Some of the arguments provided are outside the invoking actor's address space.

[ENOEXEC]

The actor file is not in a valid executable format, or cannot be run as a hot restartable actor (see the restrictions for hrfexec() ).

[ENOMEM]

No memory is available for performing the task.

[ENOSPC]

Attempt to create more than hrCtrl.maxActors hot restartable actors.

[EPERM]

Attempt to spawn a registered restartable actor that is already executing on the system.

---

Note -

Error codes generated by read(2POSIX) and open(2POSIX) may also be returned.

---

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Evolving

SEE ALSO

HR_EXIT_HDL(2RESTART) , hrKillGroup(2RESTART) , hrGetActorGroup(2RESTART) , pmmAllocate(2RESTART) , afexec(2K) , acreate(2K) , aload(2K) , astart(2K) , arun(1M) .

ChorusOS 5.0  Last Revised December 2001

NAME | SYNOPSIS | API RESTRICTIONS | FEATURES | DESCRIPTION | LIMITATIONS | RETURN VALUES | ERRORS | ATTRIBUTES | SEE ALSO