Provide an efficient indexed, thread-safe object container.
More...
Namespaces |
| namespace | bdlcc |
Detailed Description
- Outline
-
-
- Purpose:
- Provide an efficient indexed, thread-safe object container.
-
- Classes:
-
- See also:
-
- Description:
- This component provides a thread-safe and efficient templatized catalog of objects. A
bdlcc::ObjectCatalog supports efficient insertion of objects through the add method, which returns a handle that can be used for further reference to the newly added element. An element can be accessed by providing its handle to the find function. Thread-safe design implies that the element is returned by value into an object buffer rather than by reference (see this package documentation for a discussion of thread-safe container design). Likewise, an element can be modified by providing its handle and a new value to the replace method. Finally, an element can be removed by passing its handle to the remove method; the handle is then no longer valid and subsequent calls to find or remove with this handle will return 0.
bdlcc::ObjectCatalogIter provides thread safe iteration through all the objects of an object catalog of parameterized TYPE. The order of the iteration is implementation defined. Thread safe iteration is provided by (read)locking the object catalog during the iterator's construction and unlocking it at the iterator's destruction. This guarantees that during the life time of an iterator, the object catalog can't be modified (however multiple threads can still concurrently read the object catalog).
- Note that an object catalog has a maximum capacity of 2^23 items.
-
- Usage:
- This section illustrates intended use of this component.
-
- Example 1: Catalog Usage:
- Consider a client sending queries to a server asynchronously. When the response to a query arrives, the client needs to invoke the callback associated with that query. For good performance, the callback should be invoked as quickly as possible. One way to achieve this is as follows. The client creates a catalog for the functors associated with queries. It sends to the server the handle (obtained by passing the callback functor associated with the query to the
add method of catalog), along with the query. The server does not interpret this handle in any way and sends it back to the client along with the computed query result. The client, upon receiving the response, gets the functor (associated with the query) back by passing the handle (contained in the response message) to the find method of catalog.
- Assume the following declarations (we leave the implementations as undefined, as the definitions are largely irrelevant to this example):
struct Query {
};
class QueryResult {
};
class RequestMsg
{
Query d_query;
int d_handle;
public:
RequestMsg(Query query, int handle)
: d_query(query)
, d_handle(handle)
{
}
int handle() const
{
return d_handle;
}
};
class ResponseMsg
{
int d_handle;
public:
void setHandle(int handle)
{
d_handle = handle;
}
QueryResult queryResult() const
{
return QueryResult();
}
int handle() const
{
return d_handle;
}
};
void sendMessage(RequestMsg msg, RemoteAddress peer)
{
serverMutex.lock();
peer->push(msg.handle());
serverNotEmptyCondition.signal();
serverMutex.unlock();
}
void recvMessage(ResponseMsg *msg, RemoteAddress peer)
{
serverMutex.lock();
while (peer->empty()) {
serverNotEmptyCondition.wait(&serverMutex);
}
msg->setHandle(peer->front());
peer->pop();
serverMutex.unlock();
}
void getQueryAndCallback(Query *query,
bsl::function<void(QueryResult)> *callBack)
{
(void)query;
*callBack = &queryCallBack;
}
void testClientProcessQueryCpp()
{
int queriesToBeProcessed = NUM_QUERIES_TO_PROCESS;
while (queriesToBeProcessed--) {
Query query;
bsl::function<void(QueryResult)> callBack;
getQueryAndCallback(&query, &callBack);
int handle = catalog.add(callBack);
assert(handle);
RequestMsg msg(query, handle);
sendMessage(msg, serverAddress);
}
}
void testClientProcessResponseCpp()
{
int queriesToBeProcessed = NUM_QUERIES_TO_PROCESS;
while (queriesToBeProcessed--) {
ResponseMsg msg;
recvMessage(&msg, serverAddress);
int handle = msg.handle();
QueryResult result = msg.queryResult();
bsl::function<void(QueryResult)> callBack;
assert(0 == catalog.find(handle, &callBack));
callBack(result);
assert(0 == catalog.remove(handle));
}
}
extern "C" void *testClientProcessQuery(void *)
{
testClientProcessQueryCpp();
return 0;
}
extern "C" void *testClientProcessResponse(void *)
{
testClientProcessResponseCpp();
return 0;
}
-
- Example 2: Iterator Usage:
- The following code fragment shows how to use bdlcc::ObjectCatalogIter to iterate through all the objects of
catalog (a catalog of objects of type MyType). void use(bsl::function<void(QueryResult)> object)
{
(void)object;
}
catalog: Note that the associated catalog is (read)locked when the iterator is constructed and is unlocked only when the iterator is destroyed. This means that until the iterator is destroyed, all the threads trying to modify the catalog will remain blocked (even though multiple threads can concurrently read the object catalog). So clients must make sure to destroy their iterators after they are done using them. One easy way is to use the for (bdlcc::ObjectCatalogIter<MyType> it(catalog); ... as above.
