PM(3) — C LIBRARY FUNCTIONS

NAME

libpm − programming interface to the Process Manager

SYNOPSIS

#include <pm_client.h>
Pm_task_manager ∗
pm_create_manager(class, name, connection_func, task_func, other_func)
    char       ∗class;
    char       ∗name;
    Pm_call_back connection_func;
    Pm_call_back task_func;
    Pm_call_back other_func;
void
pm_set_manager_x_attrs(manager, display, window)
    Pm_task_manager ∗manager;
    Display    ∗display;
    Window      window;
Pm_status
pm_connect_manager(manager, flags)
    Pm_task_manager ∗manager;
    Pm_connection_flags flags;
Pm_status
pm_disconnect_manager(manager, flags)
    Pm_task_manager ∗manager;
    Pm_connection_flags flags;
void
pm_destroy_manager(manager)
    Pm_task_manager ∗manager;
Pm_task     ∗
pm_create_task(manager, task_id, task_name)
    Pm_task_manager ∗manager;
    Pm_task_id    task_id;
    char         ∗task_name;
void
pm_set_task_state(task, state, capabilities)
    Pm_task     ∗task;
    Pm_task_state       state;
    Pm_task_capabilities capabilities;
Pm_status
pm_destroy_task(task)
    Pm_task     ∗task;
int
pm_fd(manager)
    Pm_task_manager ∗manager;
void
pm_dispatch(manager)
    Pm_task_manager ∗manager;
void
pm_log_entry(task, time, priority, msg)
    Pm_task∗task;
    struct timeval ∗time;
    short priority;
    char ∗msg;
Pm_connection_status
pm_connection_status(manager)
    Pm_task_manager ∗manager;
void
pm_begin_update(manager)
    Pm_task_manager ∗manager;
void
pm_end_update(manager)
    Pm_task_manager ∗manager;

DESCRIPTION

The Process Manager allows the user to manipulate participating background processes. The user can view the background processes, examine messages generated by them, and manipulate them (i.e., cancel.)

The processes managed by the Process Manager are not necessarily Unix processes--rather, they are the abstractions of any background activity. To avoid confusion with Unix processes, this description will refer to the objects managed by the Process Manager as "tasks."

A "task" is a background activity--one that does not have a user-visible interface. Tasks may generate informational output which can be collected by the Process Manager.

A client of the Process Manager agrees to manage tasks of a certain type on the Process Manager’s behalf. Clients describe the tasks they manage to the Process Manager, and perform operations on the tasks at the request of the Process Manager.

These routines allow a program to communicate with the OPEN LOOK Process Manager:

pm_create_manager()
Create a client of display’s Process Manager. class indicates the type of tasks the client will be managing.

connection_func will be called when the state of the connection to the Process Manager changes.

task_func will be called when a task operation message from the Process Manager is received task_func should be declared:

void
task_func(task, command)
Pm_task ∗task;
Pm_task_command command;

Your task_func should take the action indicated by command (see below).

other_func will be called to handle non-standard messages from the Process Manager. It should look be declared:

void
other_func(manager, m)
caddr_t m;

pm_create_manager() returns a handle to a client object, or NULL on failure. This handle is then passed to the other Process Manager routines.

pm_set_manager_x_attrs()
Set some X11 attributes of the manager object. display should be an X11 display connection and window should be a window created on that display.

pm_connect_manager()
Start a connection to the Process Manager. If the flags argument has the PM_CONNECTION_WAIT flag set, this function will wait until the Process Manager accepts the connection, or until the connection attempt fails. Otherwise, this routine will send the connection message to the Process Manager but will not wait for the response. You can track the state of the Process Manager connection through the connection_func call back.

pm_destroy_manager()
Destroys manager’s connection to the Process Manager. The Process Manager will no longer consider manager’s tasks as manageable. Frees the manager object.

pm_create_task()
Creates a new task with an id of task_id (can be anything, as long as it uniquely identifies this task among the manager’s other tasks.) name will be used by the Process Manager as the tasks’s name.

pm_set_task_state()
Informs the Process manager of the state and capabilities of task. Task capabilities specify which task commands are appropriate to the task in its current state. See below.

pm_destroy_task()
Removes the task task and frees the associated storage.

pm_fd()
Returns the file descriptor associated with the manager’s connection to Process Manager. When there is input available on this descriptor (typically determined by using the select system call), clients should call pm_dispatch()

pm_dispatch()
Handles messages from the Process Manager. Call this function whenever input is available on the pm_fd() file descriptor.

pm_log_entry()
Sends a log message to the Process Manager for task task. The message will be logged with a time stamp of time, or with the current time if time is NULL. Message priorities and types are described below.

pm_begin_update()
Begins a series of task state changes or log entries. Use this routine if you will be making a large number of consecutive changes. The Process Manager may not find out about these changes until pm_end_update() is called.

pm_end_update()
Ends the series of changes started by pm_begin_update().

TASK STATES

Active tasks exists in one of two states:

State	Symbol	Description
Running	TASK_RUNNING	The task is active.
Suspended	TASK_SUSPENDED	The task has stopped (and may be continued.)

Eventually, tasks terminate. The terminal state of a task may be one of the following:

State	Symbol	Description
Completed	TASK_COMPLETED	The task completed successfully.
Failed	TASK_FAILED	The task was unsuccessful.
Cancelled	TASK_CANCELLED	The task has been cancelled by a user request.

TASK COMMANDS

Tasks may move from one state to another, either through their own actions or through user requests. User requests may be one of:

Command	Symbol	Description
Cancel	TASK_CMD_CANCEL	Terminate the task. If successful, the task will be Cancelled.
Restart	TASK_CMD_RESTART	Start the task again. If successful, the task will be Running.
Continue	TASK_CMD_CONTINUE	Continue a Suspended task. If successful, the task will be Running.
Finish Now	TASK_CMD_FINISH_NOW	Terminate the task, but ask it to generate any partial results. If successful, the task will be Cancelled.

TASK CAPABILITIES

Symbol	Description
TASK_CAN_CANCEL	Task may be cancelled.
TASK_CAN_RESTART	Task may be restarted.
TASK_CAN_CONTINUE	Task may be continued.
TASK_CAN_FINISH_NOW	Task may finish now.

BUGS AND LIMITATIONS

Only a single Process Manager connection is permitted per client. This is a deficiency of the client library.

pm_begin_update() and pm_end_update() are noops presently.

FUTURE DIRECTIONS

This interface should be considered experimental and is hence subject to change in a future release. You are encouraged to write your programs in a modular fashion, isolating any Process Manager specific functions. Comments and suggestions on this interface are welcome.

Museum

Related Articles