app.h File Reference

ISC Application Support. More...

#include <isc/eventclass.h>
#include <isc/lang.h>
#include <isc/magic.h>
#include <isc/result.h>

Go to the source code of this file.

Data Structures
struct	isc_appmethods
	app module methods. Only app driver implementations use this structure. Other clients should use the top-level interfaces (i.e., isc_app_xxx functions). magic must be ISCAPI_APPMETHODS_MAGIC. More...
struct	isc_appctx
	This structure is actually just the common prefix of an application context implementation's version of an isc_appctx_t. More...
Defines
#define	ISC_APP_H   1
#define	ISC_APPEVENT_FIRSTEVENT   (ISC_EVENTCLASS_APP + 0)
#define	ISC_APPEVENT_SHUTDOWN   (ISC_EVENTCLASS_APP + 1)
#define	ISC_APPEVENT_LASTEVENT   (ISC_EVENTCLASS_APP + 65535)
#define	ISCAPI_APPCTX_MAGIC   ISC_MAGIC('A','a','p','c')
#define	ISCAPI_APPCTX_VALID(c)
Typedefs
typedef isc_event_t	isc_appevent_t
typedef struct isc_appmethods	isc_appmethods_t
typedef isc_result_t(*	isc_appctxcreatefunc_t )(isc_mem_t *mctx, isc_appctx_t **ctxp)
Functions
ISC_LANG_BEGINDECLS isc_result_t	isc_app_ctxstart (isc_appctx_t *ctx)
isc_result_t	isc_app_start (void)
	Start an ISC library application.
isc_result_t	isc_app_ctxonrun (isc_appctx_t *ctx, isc_mem_t *mctx, isc_task_t *task, isc_taskaction_t action, void *arg)
isc_result_t	isc_app_onrun (isc_mem_t *mctx, isc_task_t *task, isc_taskaction_t action, void *arg)
	Request delivery of an event when the application is run.
isc_result_t	isc_app_ctxrun (isc_appctx_t *ctx)
isc_result_t	isc_app_run (void)
	Run an ISC library application.
isc_boolean_t	isc_app_isrunning (void)
	Return if the ISC library application is running.
isc_result_t	isc_app_ctxshutdown (isc_appctx_t *ctx)
isc_result_t	isc_app_shutdown (void)
	Request application shutdown.
isc_result_t	isc_app_ctxsuspend (isc_appctx_t *ctx)
	This has the same behavior as isc_app_ctxsuspend().
isc_result_t	isc_app_reload (void)
	Request application reload.
void	isc_app_ctxfinish (isc_appctx_t *ctx)
void	isc_app_finish (void)
	Finish an ISC library application.
void	isc_app_block (void)
	Indicate that a blocking operation will be performed.
void	isc_app_unblock (void)
	Indicate that a blocking operation is complete.
isc_result_t	isc_appctx_create (isc_mem_t *mctx, isc_appctx_t **ctxp)
	Create an application context.
void	isc_appctx_destroy (isc_appctx_t **ctxp)
	Destroy an application context.
void	isc_appctx_settaskmgr (isc_appctx_t *ctx, isc_taskmgr_t *taskmgr)
	Associate a task manager with an application context.
void	isc_appctx_setsocketmgr (isc_appctx_t *ctx, isc_socketmgr_t *socketmgr)
	Associate a socket manager with an application context.
void	isc_appctx_settimermgr (isc_appctx_t *ctx, isc_timermgr_t *timermgr)
	Associate a socket timer with an application context.
isc_result_t	isc_app_register (isc_appctxcreatefunc_t createfunc)
	Register a new application implementation and add it to the list of supported implementations. This function must be called when a different event library is used than the one contained in the ISC library.
isc_result_t	isc__app_register (void)
	A short cut function that specifies the application module in the ISC library for isc_app_register(). An application that uses the ISC library usually do not have to care about this function: it would call isc_lib_register(), which internally calls this function.

---

Detailed Description

ISC Application Support.

Dealing with program termination can be difficult, especially in a multithreaded program. The routines in this module help coordinate the shutdown process. They are used as follows by the initial (main) thread of the application:

• isc_app_start(); Call very early in main(), before any other threads have been created.

• isc_app_run(); This will post any on-run events, and then block until application shutdown is requested. A shutdown request is made by calling isc_app_shutdown(), or by sending SIGINT or SIGTERM to the process. After isc_app_run() returns, the application should shutdown itself.

• isc_app_finish(); Call very late in main().

Applications that want to use SIGHUP/isc_app_reload() to trigger reloading should check the result of isc_app_run() and call the reload routine if the result is ISC_R_RELOAD. They should then call isc_app_run() again to resume waiting for reload or termination.

Use of this module is not required. In particular, isc_app_start() is NOT an ISC library initialization routine.

This module also supports per-thread 'application contexts'. With this mode, a thread-based application will have a separate context, in which it uses other ISC library services such as tasks or timers. Signals are not caught in this mode, so that the application can handle the signals in its preferred way.

• MP: Clients must ensure that isc_app_start(), isc_app_run(), and isc_app_finish() are called at most once. isc_app_shutdown() is safe to use by any thread (provided isc_app_start() has been called previously).

The same note applies to isc_app_ctxXXX() functions, but in this case it's a per-thread restriction. For example, a thread with an application context must ensure that isc_app_ctxstart() with the context is called at most once.

• Reliability: No anticipated impact.

• Resources: None.

• Security: No anticipated impact.

• Standards: None.

Definition in file app.h.

---

Define Documentation

#define ISC_APP_H   1

Definition at line 21 of file app.h.

#define ISC_APPEVENT_FIRSTEVENT   (ISC_EVENTCLASS_APP + 0)

Definition at line 98 of file app.h.

#define ISC_APPEVENT_SHUTDOWN   (ISC_EVENTCLASS_APP + 1)

Definition at line 99 of file app.h.

Referenced by isc__app_ctxonrun().

#define ISC_APPEVENT_LASTEVENT   (ISC_EVENTCLASS_APP + 65535)

Definition at line 100 of file app.h.

#define ISCAPI_APPCTX_MAGIC   ISC_MAGIC('A','a','p','c')

Definition at line 140 of file app.h.

Referenced by isc__app_start().

#define ISCAPI_APPCTX_VALID

(

c

)

Value:

((c) != NULL && \
                                         (c)->magic == ISCAPI_APPCTX_MAGIC)

Definition at line 141 of file app.h.

Referenced by isc_app_ctxfinish(), isc_app_ctxonrun(), isc_app_ctxrun(), isc_app_ctxshutdown(), isc_app_ctxstart(), isc_app_ctxsuspend(), isc_appctx_destroy(), isc_appctx_setsocketmgr(), isc_appctx_settaskmgr(), and isc_appctx_settimermgr().

---

Typedef Documentation

typedef isc_event_t isc_appevent_t

Definition at line 96 of file app.h.

typedef struct isc_appmethods isc_appmethods_t

typedef isc_result_t(* isc_appctxcreatefunc_t)(isc_mem_t *mctx, isc_appctx_t **ctxp)

Definition at line 369 of file app.h.

---

Function Documentation

ISC_LANG_BEGINDECLS isc_result_t isc_app_ctxstart

(

isc_appctx_t *

ctx

)

Definition at line 87 of file app_api.c.

References isc_appmethods::ctxstart, isc__app_ctxstart(), isc_bind9, ISCAPI_APPCTX_VALID, isc_appctx::methods, and REQUIRE.

Referenced by dns_client_create().

isc_result_t isc_app_start

(

void

)

Start an ISC library application.

Notes: This call should be made before any other ISC library call, and as close to the beginning of the application as possible.

Requires:

• 'ctx' is a valid application context (for app_ctxstart()).

Definition at line 183 of file app_api.c.

References isc__app_start(), isc_bind9, and ISC_R_NOTIMPLEMENTED.

Referenced by dns_test_begin(), main(), and setup().

isc_result_t isc_app_ctxonrun	(	isc_appctx_t *	ctx,
		isc_mem_t *	mctx,
		isc_task_t *	task,
		isc_taskaction_t	action,
		void *	arg
	)

Definition at line 107 of file app_api.c.

References isc_appmethods::ctxonrun, isc__app_ctxonrun(), isc_bind9, ISCAPI_APPCTX_VALID, isc_appctx::methods, and REQUIRE.

Referenced by resolve_done().

isc_result_t isc_app_onrun	(	isc_mem_t *	mctx,
		isc_task_t *	task,
		isc_taskaction_t	action,
		void *	arg
	)

Request delivery of an event when the application is run.

Requires:

• isc_app_start() has been called.
• 'ctx' is a valid application context (for app_ctxonrun()).

Returns: ISC_R_SUCCESS ISC_R_NOMEMORY

Definition at line 191 of file app_api.c.

References isc__app_onrun(), isc_bind9, and ISC_R_NOTIMPLEMENTED.

Referenced by ATF_TC_BODY(), main(), and ns_server_create().

isc_result_t isc_app_ctxrun

(

isc_appctx_t *

ctx

)

Definition at line 97 of file app_api.c.

References isc_appmethods::ctxrun, isc__app_ctxrun(), isc_bind9, ISCAPI_APPCTX_VALID, isc_appctx::methods, and REQUIRE.

Referenced by dns_client_request(), dns_client_resolve(), and dns_client_update().

isc_result_t isc_app_run

(

void

)

Run an ISC library application.

Notes:

• The caller (typically the initial thread of an application) will block until shutdown is requested. When the call returns, the caller should start shutting down the application.

Requires:

• isc_app_[ctx]start() has been called.

Ensures:

• Any events requested via isc_app_onrun() will have been posted (in FIFO order) before isc_app_run() blocks.
• 'ctx' is a valid application context (for app_ctxrun()).

Returns:

• ISC_R_SUCCESS Shutdown has been requested.
• ISC_R_RELOAD Reload has been requested.

Definition at line 201 of file app_api.c.

References is_running, isc__app_run(), isc_bind9, ISC_FALSE, ISC_R_NOTIMPLEMENTED, and ISC_TRUE.

Referenced by ATF_TC_BODY(), and main().

isc_boolean_t isc_app_isrunning

(

void

)

Return if the ISC library application is running.

Returns:

• ISC_TRUE App is running.
• ISC_FALSE App is not running.

Definition at line 216 of file app_api.c.

References is_running.

Referenced by get_address().

isc_result_t isc_app_ctxshutdown

(

isc_appctx_t *

ctx

)

Definition at line 130 of file app_api.c.

References isc_appmethods::ctxshutdown, isc__app_ctxshutdown(), isc_bind9, ISCAPI_APPCTX_VALID, isc_appctx::methods, and REQUIRE.

isc_result_t isc_app_shutdown

(

void

)

Request application shutdown.

Notes:

• It is safe to call isc_app_shutdown() multiple times. Shutdown will only be triggered once.

Requires:

• isc_app_[ctx]run() has been called.
• 'ctx' is a valid application context (for app_ctxshutdown()).

Returns:

• ISC_R_SUCCESS
• ISC_R_UNEXPECTED

Definition at line 221 of file app_api.c.

References isc__app_shutdown(), isc_bind9, and ISC_R_NOTIMPLEMENTED.

Referenced by all_done(), assignwork(), dighost_shutdown(), getinput(), load_done(), ns_control_docommand(), rndc_recvdone(), and rndc_senddone().

isc_result_t isc_app_ctxsuspend

(

isc_appctx_t *

ctx

)

This has the same behavior as isc_app_ctxsuspend().

Definition at line 120 of file app_api.c.

References isc_appmethods::ctxsuspend, isc__app_ctxsuspend(), isc_bind9, ISCAPI_APPCTX_VALID, isc_appctx::methods, and REQUIRE.

Referenced by internal_update_callback(), localrequest_done(), resolve_done(), and suspend().

isc_result_t isc_app_reload

(

void

)

Request application reload.

Requires:

• isc_app_run() has been called.

Returns:

• ISC_R_SUCCESS
• ISC_R_UNEXPECTED

Definition at line 229 of file app_api.c.

References isc__app_reload(), isc_bind9, and ISC_R_NOTIMPLEMENTED.

void isc_app_ctxfinish

(

isc_appctx_t *

ctx

)

Definition at line 140 of file app_api.c.

References isc_appmethods::ctxfinish, isc__app_ctxfinish(), isc_bind9, ISCAPI_APPCTX_VALID, isc_appctx::methods, and REQUIRE.

Referenced by destroyclient().

void isc_app_finish

(

void

)

Finish an ISC library application.

Notes:

• This call should be made at or near the end of main().

Requires:

• isc_app_start() has been called.
• 'ctx' is a valid application context (for app_ctxfinish()).

Ensures:

• Any resources allocated by isc_app_start() have been released.

Definition at line 237 of file app_api.c.

References isc__app_finish(), and isc_bind9.

Referenced by cleanup_managers(), and main().

void isc_app_block

(

void

)

Indicate that a blocking operation will be performed.

Notes:

• If a blocking operation is in process, a call to isc_app_shutdown() or an external signal will abort the program, rather than allowing clean shutdown. This is primarily useful for reading user input.

Requires:

• isc_app_start() has been called.
• No other blocking operations are in progress.

Definition at line 245 of file app_api.c.

References isc__app_block(), and isc_bind9.

Referenced by do_next_command(), get_address(), get_addresses(), and get_next_command().

void isc_app_unblock

(

void

)

Indicate that a blocking operation is complete.

Notes:

• When a blocking operation has completed, return the program to a state where a call to isc_app_shutdown() or an external signal will shutdown normally.

Requires:

• isc_app_start() has been called.
• isc_app_block() has been called by the same thread.

Definition at line 253 of file app_api.c.

References isc__app_unblock(), and isc_bind9.

Referenced by do_next_command(), get_address(), get_addresses(), and get_next_command().

isc_result_t isc_appctx_create	(	isc_mem_t *	mctx,
		isc_appctx_t **	ctxp
	)

Create an application context.

Requires:

• 'mctx' is a valid memory context.
• 'ctxp' != NULL && *ctxp == NULL.

Definition at line 58 of file app_api.c.

References appctx_createfunc, createlock, isc__appctx_create(), isc_bind9, LOCK, REQUIRE, and UNLOCK.

Referenced by dns_client_create().

void isc_appctx_destroy

(

isc_appctx_t **

ctxp

)

Destroy an application context.

Requires:

• '*ctxp' is a valid application context.

Ensures:

• *ctxp == NULL.

Definition at line 75 of file app_api.c.

References ENSURE, isc__appctx_destroy(), isc_bind9, ISCAPI_APPCTX_VALID, and REQUIRE.

Referenced by destroyclient(), and dns_client_create().

void isc_appctx_settaskmgr	(	isc_appctx_t *	ctx,
		isc_taskmgr_t *	taskmgr
	)

Associate a task manager with an application context.

This must be done before running tasks within the application context.

Requires:

• 'ctx' is a valid application context.
• 'taskmgr' is a valid task manager.

Definition at line 150 of file app_api.c.

References isc__appctx_settaskmgr(), isc_bind9, ISCAPI_APPCTX_VALID, isc_appctx::methods, REQUIRE, and isc_appmethods::settaskmgr.

Referenced by isc_taskmgr_createinctx().

void isc_appctx_setsocketmgr	(	isc_appctx_t *	ctx,
		isc_socketmgr_t *	socketmgr
	)

Associate a socket manager with an application context.

This must be done before handling socket events within the application context.

Requires:

• 'ctx' is a valid application context.
• 'socketmgr' is a valid socket manager.

Definition at line 161 of file app_api.c.

References isc__appctx_setsocketmgr(), isc_bind9, ISCAPI_APPCTX_VALID, isc_appctx::methods, REQUIRE, and isc_appmethods::setsocketmgr.

Referenced by isc_socketmgr_createinctx().

void isc_appctx_settimermgr	(	isc_appctx_t *	ctx,
		isc_timermgr_t *	timermgr
	)

Associate a socket timer with an application context.

This must be done before handling timer events within the application context.

Requires:

• 'ctx' is a valid application context.
• 'timermgr' is a valid timer manager. See isc_appctx_create() above.

Definition at line 172 of file app_api.c.

References isc__appctx_settimermgr(), isc_bind9, ISCAPI_APPCTX_VALID, isc_appctx::methods, REQUIRE, and isc_appmethods::settimermgr.

Referenced by isc_timermgr_createinctx().

isc_result_t isc_app_register

(

isc_appctxcreatefunc_t

createfunc

)

Register a new application implementation and add it to the list of supported implementations. This function must be called when a different event library is used than the one contained in the ISC library.

Definition at line 42 of file app_api.c.

References appctx_createfunc, createlock, initialize(), isc_once_do, ISC_R_EXISTS, ISC_R_SUCCESS, LOCK, once, RUNTIME_CHECK, and UNLOCK.

isc_result_t isc__app_register

(

void

)

A short cut function that specifies the application module in the ISC library for isc_app_register(). An application that uses the ISC library usually do not have to care about this function: it would call isc_lib_register(), which internally calls this function.

Definition at line 1033 of file app.c.

Referenced by do_register().

---