Contexts

State for communicating with a cloud service. More...

Functions
dpl_ctx_t *	dpl_ctx_new (const char *droplet_dir, const char *profile_name)
	Create a context. More...
dpl_ctx_t *	dpl_ctx_new_from_dict (const dpl_dict_t *profile)
	Creates a new context with the profile specified in a dict. More...
void	dpl_ctx_free (dpl_ctx_t *ctx)
	Free a context. More...

Detailed Description

The dpl_ctx_t object, or "context", holds all the state and options needed to communicate with a cloud service instance. All other functions that perform operations on a cloud service require a context. Thus, creating a context is one of the very first things which a program will do when using Droplet, just after calling dpl_init().

Most programs will only ever create a single context object and will keep it for the lifetime of the program, only freeing it just before calling dpl_free() and exiting. This is not the only possible approach but it makes the most sense because

• The context holds some static configuration data which is read from a profile file when the context is created. Reading this data is expensive, and it does not change.
• The context caches connections to cloud service hosts, which allows re-use of connections between requests and thus amortises connection setup latency (such as DNS and TCP roundtrip latency) over multiple requests.
• Most programs only need to communicate with a single cloud storage service instance, so there's no need to create a second context.

An important parameter of the context is the droplet directory, which is established when the context is created. Several important files are located relative to this directory, notably the profile file. See the description of dpl_ctx_new() for details.

The context object is thread-safe and contains an internal mutex which is used to safely share access between multiple threads. This mutex is not held while requests are being made to the back end. If you need to make requests to a cloud service from multiple threads in the same process, just create a single context object and share it between all threads.

Function Documentation

void dpl_ctx_free

(

dpl_ctx_t *

ctx

)

Free a context created earlier by dpl_ctx_new(). All resources associated with the context (e.g. profile data and cached connections) are freed.

Note

If you use the connection API to create your own connections, you must release all your connections created from this context, by calling either dpl_conn_release() or dpl_conn_terminate(), before calling dpl_ctx_free().

dpl_ctx_t* dpl_ctx_new	(	const char *	droplet_dir,
		const char *	profile_name
	)

Creates and returns a new dpl_ctx_t object, or NULL on error.

Possible errors include memory allocation failure, failure to find the profile, and failure to parse the profile.

Note

If this function fails there is no way for the caller to discover what went wrong.

The droplet directory is used as the base directory for finding several important files, notably the profile file. It is the first non-NULL pathname of:

• the parameter droplet_dir, or
• the environmental variable DPLDIR, or
• "~/.droplet/".

A profile file is read to set up options for the context. The profile file is named <name>.profile where <name> is the profile's name, and is located in the droplet directory. The profile's name is the first non-NULL name of:

• the profile_name parameter, or
• the environment variable DPLPROFILE, or
• "default".

Thus, if both parameters are passed NULL the profile will be read from the file ~/.droplet/default.profile.

See Profile File for details of the profile file format.

Parameters

droplet_dir	pathname of directory containing Droplet state, or NULL
profile_name	name of the profile to use, or NULL

Returns

a new context, or NULL on error

dpl_ctx_t* dpl_ctx_new_from_dict

(

const dpl_dict_t *

profile

)

Creates a new profile and sets up the the profile information from a dict containing profile variable settings as if they had been read in from a profile file, without reading a file. This function is provided for applications which need to use the Droplet library without a profile file.

Note that to create a context without needing a droplet directory at all, applications should set the profile variable pricing_dir to an empty string.

See Profile File for details of the profile variables. The droplet directory is set by a special variable in the dict called droplet_dir, and the profile name by a special variable called profile_name.

Parameters

profile

a dict containing profile variables

Returns

a new context or NULL on error