ec_datasource_cache_query

March 26, 2020 Contributors

Name

ec_datasource_cache_query — Execute a query against a datasource cache

Synopsis

#include "modules/datasource/ecdatasource.h"

| (int) **ec_datasource_cache_query** ( | cachename, |   |
|   | query, |   |
|   | params, |   |
|   | closure); |   |

const char * <var class="pdparam">cachename</var>;
const char * <var class="pdparam">query</var>;
ECDict <var class="pdparam">params</var>;
ec_datasource_closure * <var class="pdparam">closure</var>;

Description

Execute a query against a datasource cache.

When you are done, call ec_datasource_cache_delref on any results and destroy your query using ec_datasource_destroy_query.

Parameters

cachename

A pointer to the datasource cache.

query

A pointer to the query that will be executed.

params

An ECDict of the query parameters. An ECDict is an ec_hash_table struct.

closure

A pointer to the “ec_datasource_closure” struct that holds the result set and the completion routine.

Return Values

The int returned is one of the following values:

  • ECDS_QUERY_LIMBO

  • ECDS_QUERY_FAIL

  • ECDS_QUERY_OK

  • ECDS_QUERY_ASYNC

When ECDS_QUERY_OK is returned, you can access the result field of the “ec_datasource_cache_query” struct immediately.

In the event that the query is asynchronous—it returns ECDS_QUERY_ASYNC—your callback function is called with the results. Prepare the query with a completion routine by setting the job field of the ec_data_closure struct. The job field is a struct described at ec_async_job.

Note

A query can only be asynchronous if the function calling ec_datasource_cache_query is capable of going asynchronous. This requires contextual knowledge about where the query is being executed.

The following code snippet shows how an ec_datasource_closure might be initialized:

ec_datasource_closure *dsc;
dsc = ec_malloc_size(memtype_campaign_vsize, sizeof(*dsc));
memset(dsc, 0, sizeof(*dsc));

dsc->job.completion = ECTP_COMPLETE_CALLBACK;
dsc->job.r.cb.func = completion;
dsc->job.r.cb.closure = closure;
dsc->job.job_class = ECTP_CLASS_IO;
dsc->errmsg = erroutput;

Threading

It is legal to call this function in any thread.

See Also

“ec_datasource_query_cache_entry”, “ec_data_source_query_cache” and “ec_hash_table”