Skip to content

Fix #1369 + #1370: adding GearmanClient::setXXXCallback documentation #3861

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Oct 16, 2024
Merged

Fix #1369 + #1370: adding GearmanClient::setXXXCallback documentation #3861

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
0312380
Fix #1370: adding GearmanClient::setXXXCallback callback args doc
cracksalad Oct 12, 2024
148a58c
Fix #1369 and add callback return type description
cracksalad Oct 13, 2024
5a4194b
Move GearmanClient callback to language-snippets.ent
cracksalad Oct 14, 2024
84009a3
Rephrase GearmanClient callback return value description and fix type
cracksalad Oct 15, 2024
8c35d66
Outsource GearmanClient::setXXXCallback call order note
cracksalad Oct 15, 2024
d9ce5d1
Change GearmanClient callback snippet to allow for additional parameters
cracksalad Oct 15, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 43 additions & 0 deletions language-snippets.ent
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1478,6 +1478,49 @@ encoding value will be used.</para>'>

<!ENTITY gearman.parameter.jobhandle 'The job handle assigned by the Gearman server'>

<!ENTITY gearman.parameter.callback '<varlistentry xmlns="http://docbook.org/ns/docbook">
<term><parameter>callback</parameter></term>
<listitem>
<para>
A function or method to call.
It should return a valid <link linkend="gearman.constants">Gearman return value</link>.
</para>
<para>
If no return statement is present, it defaults to <constant>GEARMAN_SUCCESS</constant>.
</para>
<methodsynopsis>
<type>int</type><methodname><replaceable>callback</replaceable></methodname>
<methodparam><type>GearmanTask</type><parameter>task</parameter></methodparam>
<methodparam><type>mixed</type><parameter>context</parameter></methodparam>
</methodsynopsis>
<variablelist>
<varlistentry>
<term><parameter>task</parameter></term>
<listitem>
<para>
The task this callback is called for.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>context</parameter></term>
<listitem>
<para>
Whatever has been passed to <methodname>GearmanClient::addTask</methodname> (or equivalent method) as <parameter>context</parameter>.
</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>'>

<!ENTITY gearman.note.callback '<note xmlns="http://docbook.org/ns/docbook">
<para>
The callback will only be triggered for tasks that are added (e.g. by calling <methodname>GearmanClient::addTask</methodname>)
after calling this method.
</para>
</note>'>

<!-- Date and time entities -->
<!ENTITY date.timezone.intro.title '<title xmlns="http://docbook.org/ns/docbook">List of Supported Timezones</title>'>

Expand Down
13 changes: 3 additions & 10 deletions reference/gearman/gearmanclient/setclientcallback.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,29 +14,22 @@
<methodparam><type>callable</type><parameter>callback</parameter></methodparam>
</methodsynopsis>
<para>
Sets the callback function for accepting data packets for a task. The callback function should
take a single argument, a <classname>GearmanTask</classname> object.
Sets the callback function for accepting data packets for a task.
</para>
<note>
<para>
This method has been replaced by <methodname>GearmanClient::setDataCallback</methodname> in
the 0.6.0 release of the Gearman extension.
</para>
</note>
&gearman.note.callback;
</refsect1>

<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>callback</parameter></term>
<listitem>
<para>
A function or method to call
</para>
</listitem>
</varlistentry>
&gearman.parameter.callback;
</variablelist>
</para>
</refsect1>
Expand Down
16 changes: 5 additions & 11 deletions reference/gearman/gearmanclient/setcompletecallback.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,31 +10,25 @@
&reftitle.description;
<methodsynopsis role="GearmanClient">
<modifier>public</modifier> <type>bool</type><methodname>GearmanClient::setCompleteCallback</methodname>
<methodparam><type>callable</type><parameter>function</parameter></methodparam>
<methodparam><type>callable</type><parameter>callback</parameter></methodparam>
</methodsynopsis>
<para>
Use to set a function to be called when a <classname>GearmanTask</classname> is completed, or
Use to set a callback function to be called when a <classname>GearmanTask</classname> is completed, or
when <methodname>GearmanJob::sendComplete</methodname> is invoked by a worker (whichever happens
first).
</para>
<para>
This callback executes only when executing a <classname>GearmanTask</classname> using
<methodname>GearmanClient::runTasks</methodname>. It is not used for individual jobs.
</para>
</para>
&gearman.note.callback;
</refsect1>

<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>function</parameter></term>
<listitem>
<para>
A function to be called
</para>
</listitem>
</varlistentry>
&gearman.parameter.callback;
</variablelist>
</para>
</refsect1>
Expand Down
15 changes: 4 additions & 11 deletions reference/gearman/gearmanclient/setcreatedcallback.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,26 +10,19 @@
&reftitle.description;
<methodsynopsis role="GearmanClient">
<modifier>public</modifier> <type>bool</type><methodname>GearmanClient::setCreatedCallback</methodname>
<methodparam><type>callable</type><parameter>function</parameter></methodparam>
<methodparam><type>callable</type><parameter>callback</parameter></methodparam>
</methodsynopsis>
<para>
Sets a function to be called when a task is received and queued by the Gearman job server.
The callback should accept a single argument, a <classname>GearmanTask</classname> object.
Sets a callback function to be called when a task is received and queued by the Gearman job server.
</para>
&gearman.note.callback;
</refsect1>

<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>function</parameter></term>
<listitem>
<para>
A function to call
</para>
</listitem>
</varlistentry>
&gearman.parameter.callback;
</variablelist>
</para>
</refsect1>
Expand Down
15 changes: 4 additions & 11 deletions reference/gearman/gearmanclient/setdatacallback.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,26 +10,19 @@
&reftitle.description;
<methodsynopsis role="GearmanClient">
<modifier>public</modifier> <type>bool</type><methodname>GearmanClient::setDataCallback</methodname>
<methodparam><type>callable</type><parameter>function</parameter></methodparam>
<methodparam><type>callable</type><parameter>callback</parameter></methodparam>
</methodsynopsis>
<para>
Sets the callback function for accepting data packets for a task. The callback function should
take a single argument, a <classname>GearmanTask</classname> object.
Sets the callback function for accepting data packets for a task.
</para>
&gearman.note.callback;
</refsect1>

<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>function</parameter></term>
<listitem>
<para>
A function or method to call
</para>
</listitem>
</varlistentry>
&gearman.parameter.callback;
</variablelist>
</para>
</refsect1>
Expand Down
14 changes: 4 additions & 10 deletions reference/gearman/gearmanclient/setexceptioncallback.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,25 +10,19 @@
&reftitle.description;
<methodsynopsis role="GearmanClient">
<modifier>public</modifier> <type>bool</type><methodname>GearmanClient::setExceptionCallback</methodname>
<methodparam><type>callable</type><parameter>function</parameter></methodparam>
<methodparam><type>callable</type><parameter>callback</parameter></methodparam>
</methodsynopsis>
<para>
Specifies a function to call when a worker for a task sends an exception.
Specifies a callback function to call when a worker for a task sends an exception.
</para>
&gearman.note.callback;
</refsect1>

<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>function</parameter></term>
<listitem>
<para>
Function to call when the worker throws an exception
</para>
</listitem>
</varlistentry>
&gearman.parameter.callback;
</variablelist>
</para>
</refsect1>
Expand Down
15 changes: 4 additions & 11 deletions reference/gearman/gearmanclient/setfailcallback.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,26 +10,19 @@
&reftitle.description;
<methodsynopsis role="GearmanClient">
<modifier>public</modifier> <type>bool</type><methodname>GearmanClient::setFailCallback</methodname>
<methodparam><type>callable</type><parameter>function</parameter></methodparam>
<methodparam><type>callable</type><parameter>callback</parameter></methodparam>
</methodsynopsis>
<para>
Sets the callback function to be used when a task does not complete successfully. The function
should accept a single argument, a <classname>GearmanTask</classname> object.
Sets the callback function to be used when a task does not complete successfully.
</para>
&gearman.note.callback;
</refsect1>

<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>function</parameter></term>
<listitem>
<para>
A function to call
</para>
</listitem>
</varlistentry>
&gearman.parameter.callback;
</variablelist>
</para>
</refsect1>
Expand Down
15 changes: 4 additions & 11 deletions reference/gearman/gearmanclient/setstatuscallback.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,26 +10,19 @@
&reftitle.description;
<methodsynopsis role="GearmanClient">
<modifier>public</modifier> <type>bool</type><methodname>GearmanClient::setStatusCallback</methodname>
<methodparam><type>callable</type><parameter>function</parameter></methodparam>
<methodparam><type>callable</type><parameter>callback</parameter></methodparam>
</methodsynopsis>
<para>
Sets a callback function used for getting updated status information from a worker. The function
should accept a single argument, a <classname>GearmanTask</classname> object.
Sets a callback function used for getting updated status information from a worker.
</para>
&gearman.note.callback;
</refsect1>

<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>function</parameter></term>
<listitem>
<para>
A function to call
</para>
</listitem>
</varlistentry>
&gearman.parameter.callback;
</variablelist>
</para>
</refsect1>
Expand Down
15 changes: 4 additions & 11 deletions reference/gearman/gearmanclient/setwarningcallback.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,26 +10,19 @@
&reftitle.description;
<methodsynopsis role="GearmanClient">
<modifier>public</modifier> <type>bool</type><methodname>GearmanClient::setWarningCallback</methodname>
<methodparam><type>callable</type><parameter>function</parameter></methodparam>
<methodparam><type>callable</type><parameter>callback</parameter></methodparam>
</methodsynopsis>
<para>
Sets a function to be called when a worker sends a warning. The callback should accept
a single argument, a <classname>GearmanTask</classname> object.
Sets a callback function to be called when a worker sends a warning.
</para>
&gearman.note.callback;
</refsect1>

<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>function</parameter></term>
<listitem>
<para>
A function to call
</para>
</listitem>
</varlistentry>
&gearman.parameter.callback;
</variablelist>
</para>
</refsect1>
Expand Down
17 changes: 5 additions & 12 deletions reference/gearman/gearmanclient/setworkloadcallback.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,28 +10,21 @@
&reftitle.description;
<methodsynopsis role="GearmanClient">
<modifier>public</modifier> <type>bool</type><methodname>GearmanClient::setWorkloadCallback</methodname>
<methodparam><type>callable</type><parameter>function</parameter></methodparam>
<methodparam><type>callable</type><parameter>callback</parameter></methodparam>
</methodsynopsis>
<para>
Sets a function to be called when a worker needs to send back data prior to job completion.
Sets a callback function to be called when a worker needs to send back data prior to job completion.
A worker can do this when it needs to send updates, send partial results, or flush data
during long running jobs. The callback should accept a single argument, a
<classname>GearmanTask</classname> object.
during long running jobs.
</para>
&gearman.note.callback;
</refsect1>

<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>function</parameter></term>
<listitem>
<para>
A function to call
</para>
</listitem>
</varlistentry>
&gearman.parameter.callback;
</variablelist>
</para>
</refsect1>
Expand Down