Configuration Client (confc)

Detailed Functional Specification. More...

Data Structures
struct	m0_confc_update_state
struct	m0_confc
struct	m0_confc_gate_ops
struct	m0_confc_ctx

Macros
#define	m0_confc_open(ctx, origin, ...)
#define	m0_confc_open_sync(result, origin, ...)

Enumerations
enum	m0_confc_state { M0_CC_READY, M0_CC_REVOKED, M0_CC_GETTING_READY, M0_CC_FAILED }

Functions
M0_INTERNAL int	m0_confc_init_wait (struct m0_confc *confc, struct m0_sm_group *sm_group, const char *confd_addr, struct m0_rpc_machine *rpc_mach, const char *local_conf, uint64_t timeout_ns)
M0_INTERNAL int	m0_confc_init (struct m0_confc *confc, struct m0_sm_group *sm_group, const char *confd_addr, struct m0_rpc_machine *rpc_mach, const char *local_conf)
M0_INTERNAL void	m0_confc_fini (struct m0_confc *confc)
M0_INTERNAL struct m0_confc *	m0_confc_from_obj (const struct m0_conf_obj *obj)
M0_INTERNAL void	m0_confc_gate_ops_set (struct m0_confc *confc, struct m0_confc_gate_ops *gops)
M0_INTERNAL int	m0_confc_ctx_init (struct m0_confc_ctx *ctx, struct m0_confc *confc)
M0_INTERNAL void	m0_confc_ctx_fini (struct m0_confc_ctx *ctx)
M0_INTERNAL void	m0_confc_ctx_fini_locked (struct m0_confc_ctx *ctx)
M0_INTERNAL int	m0_confc_reconnect (struct m0_confc *confc, struct m0_rpc_machine *rpc_mach, const char *confd_addr)
M0_INTERNAL bool	m0_confc_ctx_is_completed (const struct m0_confc_ctx *ctx)
M0_INTERNAL bool	m0_confc_ctx_is_completed_lock (const struct m0_confc_ctx *ctx)
M0_INTERNAL int32_t	m0_confc_ctx_error (const struct m0_confc_ctx *ctx)
M0_INTERNAL int32_t	m0_confc_ctx_error_lock (const struct m0_confc_ctx *ctx)
M0_INTERNAL struct m0_conf_obj *	m0_confc_ctx_result (struct m0_confc_ctx *ctx)
M0_INTERNAL void	m0_confc__open (struct m0_confc_ctx *ctx, struct m0_conf_obj *origin, const struct m0_fid *path)
M0_INTERNAL int	m0_confc__open_sync (struct m0_conf_obj **result, struct m0_conf_obj *origin, const struct m0_fid *path)
M0_INTERNAL void	m0_confc_close (struct m0_conf_obj *obj)
M0_INTERNAL void	m0_confc_open_by_fid (struct m0_confc_ctx *ctx, const struct m0_fid *fid)
M0_INTERNAL int	m0_confc_open_by_fid_sync (struct m0_confc *confc, const struct m0_fid *fid, struct m0_conf_obj **result)
M0_INTERNAL int	m0_confc_readdir (struct m0_confc_ctx *ctx, struct m0_conf_obj *dir, struct m0_conf_obj **pptr)
M0_INTERNAL int	m0_confc_readdir_sync (struct m0_conf_obj *dir, struct m0_conf_obj **pptr)
M0_INTERNAL bool	m0_confc_invariant (const struct m0_confc *confc)
M0_INTERNAL bool	m0_confc_is_inited (const struct m0_confc *confc)
M0_INTERNAL bool	m0_confc_is_online (const struct m0_confc *confc)
M0_INTERNAL struct m0_rpc_conn *	m0_confc2conn (struct m0_confc *confc)
M0_INTERNAL struct m0_rpc_session *	m0_confc2sess (struct m0_confc *confc)

Detailed Description

Detailed Functional Specification.

See also

DLD of configuration caching, Functional Specification

Macro Definition Documentation

m0_confc_open

#define m0_confc_open	(		ctx,
			origin,
			...
	)

Value:

m0_confc__open((ctx), (origin), (const struct m0_fid []){ \
                        __VA_ARGS__, M0_FID0 })

Requests an asynchronous opening of configuration object.

Parameters

ctx	Fetch context.
origin	Path origin (NULL = root configuration object).
...	Path to the requested object. Variable arguments – path components – are m0_fid initialisers (M0_FID_TINIT()); use M0_FID0 for empty path. The number of path components should not exceed M0_CONF_PATH_MAX.

Precondition

ctx->fc_origin == NULL && ctx->fc_path is empty

ctx->fc_mach.sm_state == S_INITIAL

ergo(origin != NULL, origin->co_cache == &ctx->fc_confc->cc_cache)

Definition at line 678 of file confc.h.

m0_confc_open_sync

#define m0_confc_open_sync	(		result,
			origin,
			...
	)

Value:

m0_confc__open_sync((result), (origin), (const struct m0_fid []){ \
                        __VA_ARGS__, M0_FID0 })

Opens configuration object synchronously.

If the call succeeds, *result will point to the requested object.

Parameters

result	struct m0_conf_obj **
origin	Path origin (not NULL).
...	Path to the requested object. See m0_confc_open().

Precondition

origin != NULL

Postcondition

ergo(retval == 0, (*result)->co_status == M0_CS_READY)

Example:

struct m0_conf_obj *profile_obj;
struct m0_fid       profile_fid;
int rc;

rc = m0_confc_open_sync(&profile_obj, confc->cc_root,
                        M0_CONF_ROOT_PROFILES_FID, profile_fid);

Definition at line 707 of file confc.h.

Enumeration Type Documentation

m0_confc_state

enum m0_confc_state

Configuration client states indicates different states of configuration client on configuration updates.

Enumerator
M0_CC_READY
M0_CC_REVOKED	< configuration cache is updated.
M0_CC_GETTING_READY	< configuration cache is expired.
M0_CC_FAILED	< configuration cache is being updated.

Definition at line 345 of file confc.h.

Function Documentation

m0_confc2conn()

M0_INTERNAL struct m0_rpc_conn* m0_confc2conn

(

struct m0_confc *

confc

)

Definition at line 1045 of file confc.c.

Here is the caller graph for this function:

m0_confc2sess()

M0_INTERNAL struct m0_rpc_session* m0_confc2sess

(

struct m0_confc *

confc

)

Definition at line 1050 of file confc.c.

Here is the caller graph for this function:

m0_confc__open()

M0_INTERNAL void m0_confc__open	(	struct m0_confc_ctx *	ctx,
		struct m0_conf_obj *	origin,
		const struct m0_fid *	path
	)

Definition at line 850 of file confc.c.

Here is the call graph for this function:

Here is the caller graph for this function:

m0_confc__open_sync()

M0_INTERNAL int m0_confc__open_sync	(	struct m0_conf_obj **	result,
		struct m0_conf_obj *	origin,
		const struct m0_fid *	path
	)

Definition at line 899 of file confc.c.

Here is the call graph for this function:

m0_confc_close()

M0_INTERNAL void m0_confc_close

(

struct m0_conf_obj *

obj

)

Closes configuration object opened with m0_confc_open() or m0_confc_open_sync().

m0_confc_close(NULL) is a noop.

Precondition

ergo(obj != NULL, obj->co_nrefs > 0)

Definition at line 921 of file confc.c.

Here is the call graph for this function:

m0_confc_ctx_error()

M0_INTERNAL int32_t m0_confc_ctx_error

(

const struct m0_confc_ctx *

ctx

)

Returns error status of asynchronous configuration retrieval operation.

Return values

0	The asynchronous configuration request has completed successfully.
-Exxx	The request has completed unsuccessfully.

Precondition

m0_confc_ctx_is_completed(ctx)

Definition at line 759 of file confc.c.

Here is the call graph for this function:

Here is the caller graph for this function:

m0_confc_ctx_error_lock()

M0_INTERNAL int32_t m0_confc_ctx_error_lock

(

const struct m0_confc_ctx *

ctx

)

Definition at line 765 of file confc.c.

Here is the call graph for this function:

Here is the caller graph for this function:

m0_confc_ctx_fini()

M0_INTERNAL void m0_confc_ctx_fini

(

struct m0_confc_ctx *

ctx

)

Definition at line 716 of file confc.c.

Here is the call graph for this function:

Here is the caller graph for this function:

m0_confc_ctx_fini_locked()

M0_INTERNAL void m0_confc_ctx_fini_locked

(

struct m0_confc_ctx *

ctx

)

Same as m0_confc_ctx_fini, but doesn't take sm group lock internally. Lock is needed to finalise ctx->fc_mach.

Definition at line 680 of file confc.c.

Here is the call graph for this function:

Here is the caller graph for this function:

m0_confc_ctx_init()

M0_INTERNAL int m0_confc_ctx_init	(	struct m0_confc_ctx *	ctx,
		struct m0_confc *	confc
	)

Initialises configuration retrieval context.

Precondition

confc is initialised

Note

m0_confc_ctx_init() may block at confc->cc_gops->go_check() call. It will unblock when rconfc acquires read lock or fails to do so.

This call may block.

See also

rconfc_gate_check()

Definition at line 643 of file confc.c.

Here is the call graph for this function:

Here is the caller graph for this function:

m0_confc_ctx_is_completed()

M0_INTERNAL bool m0_confc_ctx_is_completed

(

const struct m0_confc_ctx *

ctx

)

Returns true iff ctx->fc_mach has terminated or failed.

m0_confc_ctx_is_completed() can be used to filter out intermediate state transitions, signaled on ctx->fc_mach.sm_chan channel.

See also

• ‘Filtered wake-ups’ section in Waiting channels
• Get profile configuration

Definition at line 742 of file confc.c.

Here is the call graph for this function:

Here is the caller graph for this function:

m0_confc_ctx_is_completed_lock()

M0_INTERNAL bool m0_confc_ctx_is_completed_lock

(

const struct m0_confc_ctx *

ctx

)

Definition at line 749 of file confc.c.

Here is the call graph for this function:

Here is the caller graph for this function:

m0_confc_ctx_result()

M0_INTERNAL struct m0_conf_obj* m0_confc_ctx_result

(

struct m0_confc_ctx *

ctx

)

Retrieves the resulting object of a configuration request.

m0_confc_ctx_result() should only be called once, after ctx->fc_mach.sm_chan is signaled and m0_confc_ctx_error() returns 0.

m0_confc_ctx_result() sets ctx->fc_result to NULL and returns the original value.

Precondition

ctx->fc_mach.sm_state == S_TERMINAL

ctx->fc_result != NULL

Postcondition

ctx->fc_result == NULL

Definition at line 771 of file confc.c.

Here is the call graph for this function:

Here is the caller graph for this function:

m0_confc_fini()

M0_INTERNAL void m0_confc_fini

(

struct m0_confc *

confc

)

Finalises configuration client. Destroys configuration cache, freeing allocated memory.

Precondition

confc->cc_nr_ctx == 0

There are no opened (pinned) configuration objects.

Definition at line 570 of file confc.c.

Here is the call graph for this function:

Here is the caller graph for this function:

m0_confc_from_obj()

M0_INTERNAL struct m0_confc* m0_confc_from_obj

(

const struct m0_conf_obj *

obj

)

Obtains the address of m0_confc that owns given configuration object.

Definition at line 592 of file confc.c.

Here is the caller graph for this function:

m0_confc_gate_ops_set()

M0_INTERNAL void m0_confc_gate_ops_set	(	struct m0_confc *	confc,
		struct m0_confc_gate_ops *	gops
	)

Definition at line 597 of file confc.c.

Here is the call graph for this function:

Here is the caller graph for this function:

m0_confc_init()

M0_INTERNAL int m0_confc_init	(	struct m0_confc *	confc,
		struct m0_sm_group *	sm_group,
		const char *	confd_addr,
		struct m0_rpc_machine *	rpc_mach,
		const char *	local_conf
	)

Equivalent to m0_confc_init_wait() with timeout_ns = M0_TIME_NEVER.

Definition at line 560 of file confc.c.

Here is the call graph for this function:

Here is the caller graph for this function:

m0_confc_init_wait()

M0_INTERNAL int m0_confc_init_wait	(	struct m0_confc *	confc,
		struct m0_sm_group *	sm_group,
		const char *	confd_addr,
		struct m0_rpc_machine *	rpc_mach,
		const char *	local_conf,
		uint64_t	timeout_ns
	)

Initialises configuration client.

Parameters

confc	A confc instance to be initialised.
sm_group	State machine group to be associated with this confc.
confd_addr	End point address of configuration server (confd).
rpc_mach	RPC machine that will process configuration RPC items.
local_conf	Configuration string — ASCII description of configuration data to pre-load the cache with (see Pre-Loading of Configuration Cache).
timeout_ns	Confd connection timeout, nanoseconds.

Precondition

not_empty(confd_addr) || not_empty(local_conf)

ergo(not_empty(confd_addr), rpc_mach != NULL)

Definition at line 512 of file confc.c.

Here is the call graph for this function:

Here is the caller graph for this function:

m0_confc_invariant()

M0_INTERNAL bool m0_confc_invariant

(

const struct m0_confc *

confc

)

Definition at line 425 of file confc.c.

Here is the caller graph for this function:

m0_confc_is_inited()

M0_INTERNAL bool m0_confc_is_inited

(

const struct m0_confc *

confc

)

Definition at line 448 of file confc.c.

Here is the caller graph for this function:

m0_confc_is_online()

M0_INTERNAL bool m0_confc_is_online

(

const struct m0_confc *

confc

)

Definition at line 453 of file confc.c.

Here is the caller graph for this function:

m0_confc_open_by_fid()

M0_INTERNAL void m0_confc_open_by_fid	(	struct m0_confc_ctx *	ctx,
		const struct m0_fid *	fid
	)

Opens configuration object by its fid.

The operation is asynchronous. If object fid is known, it is often easier to use m0_confc_open_by_fid() instead of traversing the DAG of conf objects.

Definition at line 930 of file confc.c.

Here is the call graph for this function:

Here is the caller graph for this function:

m0_confc_open_by_fid_sync()

M0_INTERNAL int m0_confc_open_by_fid_sync	(	struct m0_confc *	confc,
		const struct m0_fid *	fid,
		struct m0_conf_obj **	result
	)

Synchronous version of m0_confc_open_by_fid().

Definition at line 943 of file confc.c.

Here is the call graph for this function:

Here is the caller graph for this function:

m0_confc_readdir()

M0_INTERNAL int m0_confc_readdir	(	struct m0_confc_ctx *	ctx,
		struct m0_conf_obj *	dir,
		struct m0_conf_obj **	pptr
	)

Requests asynchronous retrieval of the next directory entry.

Parameters

	ctx	Fetch context.
	dir	Directory.
[in]	pptr	"Current" entry.
[out]	pptr	"Next" entry.

Entries of a directory are usually present in the configuration cache. In this common case m0_confc_readdir() can fulfill the request immediately. Return values M0_CONF_DIREND and M0_CONF_DIRNEXT inform the caller that it may proceed without waiting for ctx->fc_mach.sm_chan channel to be signaled.

Return values

M0_CONF_DIRMISS	Asynchronous retrieval of configuration has been initiated. The caller should wait.
M0_CONF_DIRNEXT	*pptr now points to the next directory entry. No waiting is needed.
M0_CONF_DIREND	End of directory is reached. No waiting is needed.
-Exxx	Error.

m0_confc_readdir() puts (m0_conf_obj_put()) the configuration object referred to via ‘pptr’ input parameter.

m0_confc_readdir() pins (m0_conf_obj_get()) the resulting object in case of M0_CONF_DIRNEXT.

m0_confc_readdir() does not touch ‘ctx’ argument if the returned value is M0_CONF_DIRNEXT or M0_CONF_DIREND. ‘ctx’ can be re-used in this case.

See also

confc-fspec-recipe2

Precondition

ctx->fc_mach.sm_state == S_INITIAL

m0_conf_obj_type(dir) == &M0_CONF_DIR_TYPE && dir->co_cache == &ctx->fc_confc->cc_cache

Postcondition

ergo(M0_IN(retval, (M0_CONF_DIRNEXT, M0_CONF_DIREND)), ctx->fc_mach.sm_state == S_INITIAL)

Definition at line 990 of file confc.c.

Here is the call graph for this function:

Here is the caller graph for this function:

m0_confc_readdir_sync()

M0_INTERNAL int m0_confc_readdir_sync	(	struct m0_conf_obj *	dir,
		struct m0_conf_obj **	pptr
	)

Gets next directory entry synchronously.

Parameters

	dir	Directory.
[in]	pptr	"Current" entry.
[out]	pptr	"Next" entry.

Return values

M0_CONF_DIRNEXT	*pptr now points to the next directory entry.
M0_CONF_DIREND	End of directory is reached.
-Exxx	Error.

m0_confc_readdir_sync() puts and pins configuration objects similarly to m0_confc_readdir().

See also

m0_confc_readdir()

Example:

struct m0_conf_obj *entry;

for (entry = NULL; (rc = m0_confc_readdir_sync(dir, &entry)) > 0; )
        use(entry);

m0_confc_close(entry);

Definition at line 1020 of file confc.c.

Here is the call graph for this function:

Here is the caller graph for this function:

m0_confc_reconnect()

M0_INTERNAL int m0_confc_reconnect	(	struct m0_confc *	confc,
		struct m0_rpc_machine *	rpc_mach,
		const char *	confd_addr
	)

Lets rconfc to switch to another confd address on the fly without touching any confc internals including cache. Timely cache invalidation is a responsibility of rconfc internal routines.

Relies on internal confc locking.

Definition at line 484 of file confc.c.

Here is the call graph for this function:

Here is the caller graph for this function: