app_supervisor.h File Reference

#include "common.h"

Go to the source code of this file.

Data Structures
struct	ladish_app_supervisor_tag
struct	ladish_app_tag
Defines
#define	LADISH_APP_STATE_STOPPED   0
	app is stopped (not running)
#define	LADISH_APP_STATE_STARTED   1
	app is running and not stopping
#define	LADISH_APP_STATE_STOPPING   2
	app is stopping
#define	LADISH_APP_STATE_KILL   3
	app is being force killed
Typedefs
typedef struct ladish_app_supervisor_tag *	ladish_app_supervisor_handle
typedef struct ladish_app_tag *	ladish_app_handle
typedef void(*	ladish_app_supervisor_on_app_renamed_callback )(void *context, const char *old_name, const char *new_app_name)
typedef bool(*	ladish_app_supervisor_enum_callback )(void *context, const char *name, bool running, const char *command, bool terminal, uint8_t level, pid_t pid)
Functions
bool	ladish_app_supervisor_create (ladish_app_supervisor_handle *supervisor_handle_ptr, const char *opath, const char *name, void *context, ladish_app_supervisor_on_app_renamed_callback on_app_renamed)
void	ladish_app_supervisor_destroy (ladish_app_supervisor_handle supervisor_handle)
bool	ladish_app_supervisor_child_exit (ladish_app_supervisor_handle supervisor_handle, pid_t pid)
bool	ladish_app_supervisor_enum (ladish_app_supervisor_handle supervisor_handle, void *context, ladish_app_supervisor_enum_callback callback)
void	ladish_app_supervisor_clear (ladish_app_supervisor_handle supervisor_handle)
ladish_app_handle	ladish_app_supervisor_add (ladish_app_supervisor_handle supervisor_handle, const char *name, bool autorun, const char *command, bool terminal, uint8_t level)
void	ladish_app_supervisor_stop (ladish_app_supervisor_handle supervisor_handle)
void	ladish_app_supervisor_autorun (ladish_app_supervisor_handle supervisor_handle)
char *	ladish_app_supervisor_search_app (ladish_app_supervisor_handle supervisor_handle, pid_t pid)
const char *	ladish_app_supervisor_get_name (ladish_app_supervisor_handle supervisor_handle)
unsigned int	ladish_app_supervisor_get_running_app_count (ladish_app_supervisor_handle supervisor_handle)
bool	ladish_app_supervisor_check_app_name (ladish_app_supervisor_handle supervisor_handle, const char *name)
ladish_app_handle	ladish_app_supervisor_find_app_by_id (ladish_app_supervisor_handle supervisor_handle, uint64_t id)
const char *	ladish_app_supervisor_get_opath (ladish_app_supervisor_handle supervisor_handle)
bool	ladish_app_supervisor_start_app (ladish_app_supervisor_handle supervisor_handle, ladish_app_handle app_handle)
void	ladish_app_supervisor_stop_app (ladish_app_supervisor_handle supervisor_handle, ladish_app_handle app_handle)
void	ladish_app_supervisor_kill_app (ladish_app_supervisor_handle supervisor_handle, ladish_app_handle app_handle)
void	ladish_app_supervisor_remove_app (ladish_app_supervisor_handle supervisor_handle, ladish_app_handle app_handle)
const char *	ladish_app_get_commandline (ladish_app_handle app_handle)
unsigned int	ladish_app_get_state (ladish_app_handle app_handle)
bool	ladish_app_is_running (ladish_app_handle app_handle)
const char *	ladish_app_get_name (ladish_app_handle app_handle)
Variables
struct dbus_interface_descriptor	g_iface_app_supervisor

---

Detailed Description

---

Typedef Documentation

typedef struct ladish_app_supervisor_tag * ladish_app_supervisor_handle

App supervisor object handle (pointer to opaque data)

typedef struct ladish_app_tag * ladish_app_handle

App object handle (pointer to opaque data)

The app objects are owned by the app supervisor objects (there is not refcounting)

typedef void(* ladish_app_supervisor_on_app_renamed_callback)(void *context, const char *old_name, const char *new_app_name)

Type of function that is called when app is renamed

Parameters:

[in]	context	User defined context that was supplied to ladish_app_supervisor_create()
[in]	old_name	Old name of the app
[in]	new_name	New name of the app

typedef bool(* ladish_app_supervisor_enum_callback)(void *context, const char *name, bool running, const char *command, bool terminal, uint8_t level, pid_t pid)

Type of function that is called during app enumeration

Parameters:

[in]	context	User defined context that was supplied to ladish_app_supervisor_enum()
[in]	name	Name of the app
[in]	running	Whether the app is currently running
[in]	command	Commandline that is used to start the app
[in]	terminal	Whether the app is started in terminal
[in]	level	The level that app was started in
[in]	pid	PID of the app; Zero if app is not start

---

Function Documentation

bool ladish_app_supervisor_create	(	ladish_app_supervisor_handle *	supervisor_handle_ptr,
		const char *	opath,
		const char *	name,
		void *	context,
		ladish_app_supervisor_on_app_renamed_callback	on_app_renamed
	)

Create app supervisor object

Parameters:

[out]	supervisor_handle_ptr	Pointer to variable that will receive supervisor handle
[in]	opath	Unique D-Bus object path for supervisor being created
[in]	name	Name of the supervisor
[in]	context	User defined context to be supplied when the callback suppiled through the on_app_renamed parameter is called
[in]	on_app_renamed	Callback to call when app is renamed

Returns:

success status

void ladish_app_supervisor_destroy

(

ladish_app_supervisor_handle

supervisor_handle

)

Destroy app supervisor object

Parameters:

[in]

supervisor_handle

supervisor object handle

bool ladish_app_supervisor_child_exit	(	ladish_app_supervisor_handle	supervisor_handle,
		pid_t	pid
	)

Mark that app has quit

This function is called to mark that app has quit. Must not be called from signal handler because app supervisor object is not thread safe.

Parameters:

[in]	supervisor_handle	supervisor object handle
[in]	pid	of the app whose termination was detected

bool ladish_app_supervisor_enum	(	ladish_app_supervisor_handle	supervisor_handle,
		void *	context,
		ladish_app_supervisor_enum_callback	callback
	)

Iterate apps that are owned by supervisor

Parameters:

[in]	supervisor_handle	supervisor object handle
[in]	context	User defined context to be supplied when the callback suppiled through the callback parameter is called
[in]	callback	Callback to call for each app

void ladish_app_supervisor_clear

(

ladish_app_supervisor_handle

supervisor_handle

)

It is not clear what this function is supposed to do

Parameters:

[in]

supervisor_handle

supervisor object handle

ladish_app_handle ladish_app_supervisor_add	(	ladish_app_supervisor_handle	supervisor_handle,
		const char *	name,
		bool	autorun,
		const char *	command,
		bool	terminal,
		uint8_t	level
	)

Add app. Apps are added in stopped state

Parameters:

[in]	supervisor_handle	supervisor object handle
[in]	name	Name of the app
[in]	autorun	whether to start the app when ladish_app_supervisor_autorun() is called
[in]	command	Commandline that is used to start the app
[in]	terminal	Whether the app is started in terminal
[in]	level	The level that app was started in

Returns:

app handle on success; NULL on failure; the app handle is owned by the app supervisor object

void ladish_app_supervisor_stop

(

ladish_app_supervisor_handle

supervisor_handle

)

Initiate stop of all apps owned by this supervisor

Parameters:

[in]

supervisor_handle

supervisor object handle

void ladish_app_supervisor_autorun

(

ladish_app_supervisor_handle

supervisor_handle

)

Start all apps that were added with autorun enabled

Parameters:

[in]

supervisor_handle

supervisor object handle

char* ladish_app_supervisor_search_app	(	ladish_app_supervisor_handle	supervisor_handle,
		pid_t	pid
	)

Search app by pid and return its name

TODO: this should be renamed to match the fact that it returns app name and not app handle. Implementing ladish_app_supervisor_find_app_by_pid() makes sense as well.

Parameters:

[in]	supervisor_handle	supervisor object handle
[in]	pid	pid of the app to search for

Returns:

app name on success; NULL if app is not found

const char* ladish_app_supervisor_get_name

(

ladish_app_supervisor_handle

supervisor_handle

)

Get name of the supervisor

TODO: This should be probably removed in favour of ladish_app_supervisor_get_opath(); it is used for debuging purposes only

Parameters:

[in]

supervisor_handle

supervisor object handle

Return values:

app

name; the buffer is owned by the app supervisor object

unsigned int ladish_app_supervisor_get_running_app_count

(

ladish_app_supervisor_handle

supervisor_handle

)

Get number of apps that are currently running

Parameters:

[in]

supervisor_handle

supervisor object handle

Returns:

Number of apps that are currently running

bool ladish_app_supervisor_check_app_name	(	ladish_app_supervisor_handle	supervisor_handle,
		const char *	name
	)

Check whether app with name supplied name exists

Parameters:

[in]	supervisor_handle	supervisor object handle
[in]	name	name of the app to search for

Return values:

	true	app with supplied name exists
	false	app with supplied name does not exist

ladish_app_handle ladish_app_supervisor_find_app_by_id	(	ladish_app_supervisor_handle	supervisor_handle,
		uint64_t	id
	)

Find app by id (as exposed through the D-Bus interface)

Parameters:

[in]	supervisor_handle	supervisor object handle
[in]	id	id of the app

Returns:

app handle on success; NULL if app is not found; the app handle is owned by the app supervisor object

const char* ladish_app_supervisor_get_opath

(

ladish_app_supervisor_handle

supervisor_handle

)

The the D-Bus object path for the supervisor.

Parameters:

[in]

supervisor_handle

supervisor object handle

Return values:

supervisor

name; the buffer is owned by the app supervisor object

bool ladish_app_supervisor_start_app	(	ladish_app_supervisor_handle	supervisor_handle,
		ladish_app_handle	app_handle
	)

Start an app. The app must be in stopped state.

Parameters:

[in]	supervisor_handle	supervisor object handle
[in]	app_handle	Handle of app to start

Returns:

success status

void ladish_app_supervisor_stop_app	(	ladish_app_supervisor_handle	supervisor_handle,
		ladish_app_handle	app_handle
	)

Stop an app. The app must be in started state.

Parameters:

[in]	supervisor_handle	supervisor object handle
[in]	app_handle	Handle of app to stop

void ladish_app_supervisor_kill_app	(	ladish_app_supervisor_handle	supervisor_handle,
		ladish_app_handle	app_handle
	)

Force kill an app. The app must be in started state.

Parameters:

[in]	supervisor_handle	supervisor object handle
[in]	app_handle	Handle of app to kill

void ladish_app_supervisor_remove_app	(	ladish_app_supervisor_handle	supervisor_handle,
		ladish_app_handle	app_handle
	)

Remove an app. The app must be in stopped state.

Parameters:

[in]	supervisor_handle	supervisor object handle
[in]	app_handle	Handle of app to remove

const char* ladish_app_get_commandline

(

ladish_app_handle

app_handle

)

Get commandline for an app.

Parameters:

[in]

app_handle

app object handle

Return values:

app

commandline; the buffer is owned by the app supervisor object

unsigned int ladish_app_get_state

(

ladish_app_handle

app_handle

)

Get app state

Parameters:

[in]

app_handle

app object handle

Returns:

app state

Return values:

	LADISH_APP_STATE_STOPPED	app is stopped (not running)
	LADISH_APP_STATE_STARTED	app is running and not stopping or being killed
	LADISH_APP_STATE_STOPPING	app is stopping
	LADISH_APP_STATE_KILL	app is being force killed

bool ladish_app_is_running

(

ladish_app_handle

app_handle

)

Check whether app is currently running

Parameters:

[in]

app_handle

app object handle

Return values:

	true	App is running
	false	App is not running

const char* ladish_app_get_name

(

ladish_app_handle

app_handle

)

Get app name

Parameters:

[in]

app_handle

app object handle

Return values:

app

name; the buffer is owned by the app supervisor

---

Variable Documentation

struct dbus_interface_descriptor g_iface_app_supervisor

D-Bus interface descriptor for the app supervisor interface. The call context must be a ladish_app_supervisor_handle