Source Format Enforcement (#763)

[thirdparty/squid.git] / src / base / AsyncJobs.dox

diff --git a/src/base/AsyncJobs.dox b/src/base/AsyncJobs.dox
index 296ed81f4d8048fef6dce10353655bc7d1750b95..1437c22bba11b579e82da8e64033d5d163f55c84 100644 (file)
--- a/src/base/AsyncJobs.dox
+++ b/src/base/AsyncJobs.dox
@@ -1,20 +1,28 @@
+/*
+ * Copyright (C) 1996-2021 The Squid Software Foundation and contributors
+ *
+ * Squid software is distributed under GPLv2+ license and includes
+ * contributions from numerous individuals and organizations.
+ * Please see the COPYING and CONTRIBUTORS files for details.
+ */
+
 /**
 \defgroup AsyncJobs Asynchronous Jobs
 \ingroup Components
  
-\section Terminology Terminology
+\section AsyncJobsTerminology Terminology
 
 - \b Job: an AsyncJob object.
 - \b Creator: the code creating the job. Usually the Initiator.
-- \b Start: the act of calling AsyncStart with a job pointer.
+- \b Start: the act of calling AsyncJob::Start with a job pointer.
 - \b Initiator: the code starting the job. Usually the Creator.
 
-\section Life Typical life cycle
+\section AsyncJobsLifecycle Typical life cycle
 
 -# Creator creates and initializes a job.
--# Initiator starts the job. If Initiator expects
-to communicate with the started job, then it stores the job pointer
-returned by AsyncStart.
+-# If Initiator expects to communicate with the job after start,
+   then it stores the job pointer
+-# Initiator starts the job by calling AsyncJob::Start.
 -# The job's start() method is called. The method usually schedules
 some I/O or registers to receive some other callbacks.
 -# The job runs and does what it is supposed to do. This usually involves
@@ -27,24 +35,25 @@ then notifying Initiator of the final result.
 
 If you want to do something before starting the job, do it in the constructor
 or some custom method that the job creator will call _before_ calling
-AsyncStart():
+AsyncJob::Start():
 
-    std::auto_ptr<MyJob> job(new MyJob(...)); // sync/blocking
+    std::unique_ptr<MyJob> job(new MyJob(...)); // sync/blocking
     job->prepare(...); // sync/blocking
     job->prepareSomethingElse(...); // sync/blocking
     AsyncStart(job.release()); // non-blocking
 
 If you do not need complex preparations, it is better to do this instead:
 
-    AsyncStart(new MyJob(...));
+    AsyncJob::Start(new MyJob(...));
 
 Keep in mind that you have no async debugging, cleanup, and protections until
-you call AsyncStart with a job pointer.
+you call AsyncJob::Start with a job pointer.
 
 
-\section Rules Basic rules
+\section AsyncJobsBasicRules Basic rules
 
-- To start a job, use AsyncStart. Do not start the same job more than once.
+- To start a job, use AsyncJob::Start.
+  Do not start the same job more than once.
 
 - Never call start() directly. Treat this method as main() in C/C++.