Skip to content

Commit

Permalink
Cleanup bdlmt docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@osubboo
osubboo committed Sep 23, 2024
1 parent 76ee7fd commit d8275e9
Show file tree
Hide file tree
Showing 5 changed files with 159 additions and 162 deletions.
10 changes: 5 additions & 5 deletions groups/bdl/bdlmt/bdlmt_multiprioritythreadpool.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -148,7 +148,7 @@ BSLS_IDENT("$Id: $")
// less urgent jobs did not:
// ```
// bdlmt::MultipriorityThreadPool pool(20, // # of threads
// 2); // # of priorities
// 2); // # of priorities
//
// bsls::TimeInterval finishTime =
// bsls::SystemTime::nowRealtimeClock() + 0.5;
Expand Down Expand Up @@ -194,14 +194,14 @@ BSLS_IDENT("$Id: $")
// };
//
// bool isStillPrime[TOP_NUMBER];
// bsls::AtomicInt scannedTo[TOP_NUMBER]; // if 'P' is a prime, what is the
// // highest multiple of 'P' that
// bsls::AtomicInt scannedTo[TOP_NUMBER]; // if `P` is a prime, what is the
// // highest multiple of `P` that
// // we have marked
// // 'isStillPrime[P] = false'
// // `isStillPrime[P] = false`
//
// bsls::AtomicInt maxPrimeFound; // maximum prime identified so far
// int primeNumbers[TOP_NUMBER]; // elements in the range
// // '0 .. numPrimeNumbers - 1' are
// // `0 .. numPrimeNumbers - 1` are
// // the prime numbers we have found
// // so far
// bsls::AtomicInt numPrimeNumbers;
Expand Down
87 changes: 44 additions & 43 deletions groups/bdl/bdlmt/bdlmt_multiqueuethreadpool.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -49,11 +49,11 @@ BSLS_IDENT("$Id: $")
//
///Thread Safety
///-------------
// The `bdlmt::MultiQueueThreadPool` class is *fully thread-safe* (i.e., all
// The `bdlmt::MultiQueueThreadPool` class is **fully thread-safe** (i.e., all
// public methods of a particular instance may safely execute concurrently).
// This class is also *thread-enabled* (i.e., the class does not function
// This class is also **thread-enabled** (i.e., the class does not function
// correctly in a non-multi-threading environment). See `bsldoc_glossary` for
// complete definitions of *fully thread-safe* and *thread-enabled*.
// complete definitions of **fully thread-safe** and **thread-enabled**.
//
///Job Execution Batch Size
///------------------------
Expand Down Expand Up @@ -100,10 +100,10 @@ BSLS_IDENT("$Id: $")
// First, we present a class used to manage a word, and the set of files which
// contain that word:
// ```
// /// This class defines a search profile consisting of a word and a set
// /// of files (given by name) that contain the word. Here, "word" is
// /// defined as any string of characters.
// class my_SearchProfile {
// // This class defines a search profile consisting of a word and a set
// // of files (given by name) that contain the word. Here, "word" is
// // defined as any string of characters.
//
// bsl::string d_word; // word to search for
// bsl::set<bsl::string> d_fileSet; // set of matching files
Expand All @@ -115,32 +115,35 @@ BSLS_IDENT("$Id: $")
//
// public:
// // CREATORS
//
// /// Create a `my_SearchProfile` with the specified `word`.
// /// Optionally specify a `basicAllocator` used to supply memory. If
// /// `basicAllocator` is 0, the default memory allocator is used.
// my_SearchProfile(const char *word,
// bslma::Allocator *basicAllocator = 0);
// // Create a 'my_SearchProfile' with the specified 'word'.
// // Optionally specify a 'basicAllocator' used to supply memory. If
// // 'basicAllocator' is 0, the default memory allocator is used.
//
// /// Destroy this search profile.
// ~my_SearchProfile();
// // Destroy this search profile.
//
// // MANIPULATORS
//
// /// Insert the specified `file` into the file set maintained by this
// /// search profile.
// void insert(const char *file);
// // Insert the specified 'file' into the file set maintained by this
// // search profile.
//
// // ACCESSORS
//
// /// Return `true` if the specified `file` matches this search
// /// profile.
// bool isMatch(const char *file) const;
// // Return 'true' if the specified 'file' matches this search
// // profile.
//
// /// Return a reference to the non-modifiable file set maintained by
// /// this search profile.
// const bsl::set<bsl::string>& fileSet() const;
// // Return a reference to the non-modifiable file set maintained by
// // this search profile.
//
// /// Return a reference to the non-modifiable word maintained by this
// /// search profile.
// const bsl::string& word() const;
// // Return a reference to the non-modifiable word maintained by this
// // search profile.
// };
// ```
// And the implementation:
Expand Down Expand Up @@ -204,10 +207,10 @@ BSLS_IDENT("$Id: $")
// file name. If the specified file name matches the profile, it is inserted
// into the profile's file list.
// ```
// /// Insert the specified `file` to the file set of the specified search
// /// `profile` if `file` matches the `profile`.
// void my_SearchCb(my_SearchProfile* profile, const char *file)
// {
// // Insert the specified 'file' to the file set of the specified search
// // 'profile' if 'file' matches the 'profile'.
//
// assert(profile);
// assert(file);
Expand All @@ -227,19 +230,19 @@ BSLS_IDENT("$Id: $")
// profile. Lastly, `fastSearch` collects the results, which is the set
// intersection of each file set maintained by the individual search profiles.
// ```
// /// Return the set of files, specified by `fileList`, containing every
// /// word in the specified `wordList`, in the specified `resultSet`.
// /// Optionally specify `repetitions`, the number of repetitions to run
// /// the search jobs (it is used to increase the load for performance
// /// testing). Optionally specify a `basicAllocator` used to supply
// /// memory. If `basicAllocator` is 0, the default memory allocator is
// /// used.
// void fastSearch(const bsl::vector<bsl::string>& wordList,
// const bsl::vector<bsl::string>& fileList,
// bsl::set<bsl::string>& resultSet,
// int repetitions = 1,
// bslma::Allocator *basicAllocator = 0)
// {
// // Return the set of files, specified by 'fileList', containing every
// // word in the specified 'wordList', in the specified 'resultSet'.
// // Optionally specify 'repetitions', the number of repetitions to run
// // the search jobs (it is used to increase the load for performance
// // testing). Optionally specify a 'basicAllocator' used to supply
// // memory. If 'basicAllocator' is 0, the default memory allocator is
// // used.
//
// typedef bsl::vector<bsl::string> ListType;
// // This type is defined for notational convenience when iterating
Expand Down Expand Up @@ -405,7 +408,7 @@ class MultiQueueThreadPool_Queue {

// DATA
MultiQueueThreadPool *d_multiQueueThreadPool_p;
// the 'MultiQueueThreadPool'
// the `MultiQueueThreadPool`
// that owns this object

bsl::deque<Job> d_list; // queue of jobs to be
Expand Down Expand Up @@ -472,13 +475,12 @@ class MultiQueueThreadPool_Queue {
/// `prepareForDeletion` has already been called on this object.
int enable();

/// Disable enqueuing to this queue. Return 0 on success, and a
/// non-zero value otherwise. This method will fail (with an error) if
/// Disable enqueuing to this queue. Return 0 on success, and a non-zero
/// value otherwise. This method will fail (with an error) if
/// `prepareForDeletion` has already been called on this object.
int disable();

/// Block until all threads waiting for this queue to pause are
/// released.
/// Block until all threads waiting for this queue to pause are released.
void drainWaitWhilePausing();

/// Execute the `Job` at the front of this queue, dequeue the `Job`, and
Expand Down Expand Up @@ -608,7 +610,7 @@ class MultiQueueThreadPool {

ThreadPool *d_threadPool_p; // threads for queue processing

bool d_threadPoolIsOwned; // 'true' if thread pool is owned
bool d_threadPoolIsOwned; // `true` if thread pool is owned

bdlcc::ObjectPool<
MultiQueueThreadPool_Queue,
Expand All @@ -619,7 +621,7 @@ class MultiQueueThreadPool {
QueueRegistry d_queueRegistry; // registry of queues

int d_nextId; // next id to provide from
// 'createQueue'
// `createQueue`

State d_state; // maintains internal state

Expand Down Expand Up @@ -850,7 +852,7 @@ class MultiQueueThreadPool {
// ACCESSORS

/// Return an instantaneous snapshot of the execution batch size (see
/// {`Job Execution Batch Size`}) of the queue associated with the
/// [](#Job Execution Batch Size)) of the queue associated with the
/// specified `id`, or -1 if `id` is not a valid queue id. When a
/// thread is selecting jobs for processing, if fewer than `batchSize`
/// jobs are available then only the available jobs will be processed in
Expand All @@ -875,16 +877,15 @@ class MultiQueueThreadPool {
/// enqueued.
int numElements() const;

/// Return an instantaneous snapshot of the number of elements enqueued
/// in the queue associated with the specified `id` as a non-negative
/// integer, or -1 if `id` does not specify a valid queue.
/// Return an instantaneous snapshot of the number of elements enqueued in
/// the queue associated with the specified `id` as a non-negative integer,
/// or -1 if `id` does not specify a valid queue.
int numElements(int id) const;

/// Load into the specified `numExecuted` and `numEnqueued` the number
/// of items dequeued / enqueued (respectively) since the last time
/// these values were reset. Optionally specify a `numDeleted` used to
/// load into the number of items deleted since the last time this value
/// was reset.
/// Load into the specified `numExecuted` and `numEnqueued` the number of
/// items dequeued / enqueued (respectively) since the last time these
/// values were reset. Optionally specify a `numDeleted` used to load into
/// the number of items deleted since the last time this value was reset.
void numProcessed(int *numExecuted,
int *numEnqueued,
int *numDeleted = 0) const;
Expand Down
65 changes: 33 additions & 32 deletions groups/bdl/bdlmt/bdlmt_threadmultiplexor.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -47,11 +47,11 @@ BSLS_IDENT("$Id: $")
//
///Thread Safety
///-------------
// The `bdlmt::ThreadMultiplexor` class is both *fully thread-safe* (i.e., all
// non-creator methods can correctly execute concurrently), and is
// *thread-enabled* (i.e., the class does not function correctly in a
// The `bdlmt::ThreadMultiplexor` class is both **fully thread-safe** (i.e.,
// all non-creator methods can correctly execute concurrently), and is
// **thread-enabled** (i.e., the class does not function correctly in a
// non-multi-threading environment). See `bsldoc_glossary` for complete
// definitions of *fully thread-safe* and *thread-enabled*.
// definitions of **fully thread-safe** and **thread-enabled**.
//
///Usage
///-----
Expand All @@ -71,16 +71,16 @@ BSLS_IDENT("$Id: $")
// to instantiate the job queue, and owns an instance of
// `bdlmt::ThreadMultiplexor`, used to process jobs.
// ```
// /// This class defines a generic processor for user-defined functions
// /// ("jobs"). Jobs specified to the `processJob` method are executed
// /// in the thread pool specified at construction.
// class JobQueue {
// // This class defines a generic processor for user-defined functions
// // ("jobs"). Jobs specified to the 'processJob' method are executed
// // in the thread pool specified at construction.
//
// public:
// // PUBLIC TYPES
//
// /// A callback of this type my be specified to the `processJob` method.
// typedef bdlmt::ThreadMultiplexor::Job Job;
// // A callback of this type my be specified to the 'processJob'
// // method.
//
// private:
// // DATA
Expand All @@ -94,23 +94,25 @@ BSLS_IDENT("$Id: $")
//
// public:
// // CREATORS
//
// /// Create a job queue that executes jobs in the specified
// /// 'threadPool' using no more than the specified 'maxProcessors'.
// /// Optionally specify a 'basicAllocator' used to supply memory. If
// /// 'basicAllocator' is 0, the currently installed default allocator
// /// is used.
// JobQueue(int maxProcessors,
// bdlmt::FixedThreadPool *threadPool,
// bslma::Allocator *basicAllocator = 0);
// // Create a job queue that executes jobs in the specified
// // 'threadPool' using no more than the specified 'maxProcessors'.
// // Optionally specify a 'basicAllocator' used to supply memory. If
// // 'basicAllocator' is 0, the currently installed default allocator
// // is used.
//
// /// Destroy this object.
// ~JobQueue();
// // Destroy this object.
//
// // MANIPULATORS
//
// /// Process the specified `job` in the thread pool specified at
// /// construction. Return 0 on success, and a non-zero value
// /// otherwise.
// int processJob(const Job& job);
// // Process the specified 'job' in the thread pool specified at
// // construction. Return 0 on success, and a non-zero value
// // otherwise.
// };
// ```
// The maximum number of processors for the multiplexor instance owned by each
Expand Down Expand Up @@ -251,10 +253,10 @@ class ThreadMultiplexor {

private:
// DATA
bslma::Allocator *d_allocator_p; // memory allocator (held)
bslma::Allocator *d_allocator_p; // memory allocator (held)
bdlcc::FixedQueue<Job> *d_jobQueue_p; // pending job queue (owned)
bsls::AtomicInt d_numProcessors; // current number of processors
int d_maxProcessors; // maximum number of processors
bsls::AtomicInt d_numProcessors; // current number of processors
int d_maxProcessors; // maximum number of processors

private:
// PRIVATE MANIPULATORS
Expand All @@ -279,13 +281,12 @@ class ThreadMultiplexor {

/// Create a thread multiplexor which uses, at most, the specified
/// `maxProcessors` number of threads to process user-specified jobs,
/// identified as callbacks of type `Job`. Jobs that cannot be
/// processed immediately are placed on a queue having the specified
/// `maxQueueSize` to be processed by the next free thread. Optionally
/// specify a `basicAllocator` used to supply memory. If
/// `basicAllocator` is 0, the currently installed default allocator is
/// used. The behavior is undefined unless `0 < maxProcessors` and
/// `0 < maxQueueSize`.
/// identified as callbacks of type `Job`. Jobs that cannot be processed
/// immediately are placed on a queue having the specified `maxQueueSize`
/// to be processed by the next free thread. Optionally specify a
/// `basicAllocator` used to supply memory. If `basicAllocator` is 0, the
/// currently installed default allocator is used. The behavior is
/// undefined unless `0 < maxProcessors` and `0 < maxQueueSize`.
ThreadMultiplexor(int maxProcessors,
int maxQueueSize,
bslma::Allocator *basicAllocator = 0);
Expand All @@ -297,10 +298,10 @@ class ThreadMultiplexor {

/// Process the specified `job` functor in the calling thread if the
/// current number of processors is less than the maximum number of
/// processors. Otherwise, enqueue `job` to the pending job queue.
/// Return 0 on success, and a non-zero value otherwise. Note that the
/// only requirements on `t_JOBTYPE` are that it defines `operator()`,
/// having a `void` return type, and that it defines a copy constructor.
/// processors. Otherwise, enqueue `job` to the pending job queue. Return
/// 0 on success, and a non-zero value otherwise. Note that the only
/// requirements on `t_JOBTYPE` are that it defines `operator()`, having a
/// `void` return type, and that it defines a copy constructor.
template <class t_JOBTYPE>
int processJob(const t_JOBTYPE& job);

Expand Down
Loading

0 comments on commit d8275e9

Please sign in to comment.