← Back to branch summary

~ubuntu-branches/ubuntu/trusty/erlang/trusty

« back to all changes in this revision

Viewing changes to lib/stdlib/doc/src/gen_server.xml

  • Committer: Bazaar Package Importer
  • Author(s): Clint Byrum
  • Date: 2011-05-05 15:48:43 UTC
  • mfrom: (3.5.13 sid)
  • Revision ID: james.westby@ubuntu.com-20110505154843-0om6ekzg6m7ugj27
Tags: 1:14.b.2-dfsg-3ubuntu1
* Merge from debian unstable.  Remaining changes:
  - Drop libwxgtk2.8-dev build dependency. Wx isn't in main, and not
    supposed to.
  - Drop erlang-wx binary.
  - Drop erlang-wx dependency from -megaco, -common-test, and -reltool, they
    do not really need wx. Also drop it from -debugger; the GUI needs wx,
    but it apparently has CLI bits as well, and is also needed by -megaco,
    so let's keep the package for now.
  - debian/patches/series: Do what I meant, and enable build-options.patch
    instead.
* Additional changes:
  - Drop erlang-wx from -et
* Dropped Changes:
  - patches/pcre-crash.patch: CVE-2008-2371: outer level option with
    alternatives caused crash. (Applied Upstream)
  - fix for ssl certificate verification in newSSL: 
    ssl_cacertfile_fix.patch (Applied Upstream)
  - debian/patches/series: Enable native.patch again, to get stripped beam
    files and reduce the package size again. (build-options is what
    actually accomplished this)
  - Remove build-options.patch on advice from upstream and because it caused
    odd build failures.

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/stdlib/doc/src/gen_server.xml
4
4
<erlref>
5
5
  <header>
6
6
    <copyright>
7
 
      <year>1996</year><year>2009</year>
 
7
      <year>1996</year><year>2010</year>
8
8
      <holder>Ericsson AB. All Rights Reserved.</holder>
9
9
    </copyright>
10
10
    <legalnotice>
13
13
      compliance with the License. You should have received a copy of the
14
14
      Erlang Public License along with this software. If not, it can be
15
15
      retrieved online at http://www.erlang.org/.
16
 
    
 
16
 
17
17
      Software distributed under the License is distributed on an "AS IS"
18
18
      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
19
19
      the License for the specific language governing rights and limitations
20
20
      under the License.
21
 
    
 
21
 
22
22
    </legalnotice>
23
23
 
24
24
    <title>gen_server</title>
598
598
        <p>The function should return the updated internal state.</p>
599
599
      </desc>
600
600
    </func>
 
601
    <func>
 
602
      <name>Module:format_status(Opt, [PDict, State]) -> Status</name>
 
603
      <fsummary>Optional function for providing a term describing the
 
604
        current gen_server status.</fsummary>
 
605
      <type>
 
606
        <v>Opt = normal | terminate</v>
 
607
        <v>PDict = [{Key, Value}]</v>
 
608
        <v>State = term()</v>
 
609
        <v>Status = term()</v>
 
610
      </type>
 
611
      <desc>
 
612
        <note>
 
613
          <p>This callback is optional, so callback modules need not
 
614
            export it. The gen_server module provides a default
 
615
            implementation of this function that returns the callback
 
616
            module state.</p>
 
617
        </note>
 
618
        <p>This function is called by a gen_server process when:</p>
 
619
        <list typed="bulleted">
 
620
          <item>One
 
621
          of <seealso marker="sys#get_status/1">sys:get_status/1,2</seealso>
 
622
          is invoked to get the gen_server status. <c>Opt</c> is set
 
623
          to the atom <c>normal</c> for this case.</item>
 
624
          <item>The gen_server terminates abnormally and logs an
 
625
          error. <c>Opt</c> is set to the atom <c>terminate</c> for this
 
626
          case.</item>
 
627
        </list>
 
628
        <p>This function is useful for customising the form and
 
629
          appearance of the gen_server status for these cases. A
 
630
          callback module wishing to customise
 
631
          the <c>sys:get_status/1,2</c> return value as well as how
 
632
          its status appears in termination error logs exports an
 
633
          instance of <c>format_status/2</c> that returns a term
 
634
          describing the current status of the gen_server.</p>
 
635
        <p><c>PDict</c> is the current value of the gen_server's
 
636
          process dictionary.</p>
 
637
        <p><c>State</c> is the internal state of the gen_server.</p>
 
638
        <p>The function should return <c>Status</c>, a term that
 
639
          customises the details of the current state and status of
 
640
          the gen_server. There are no restrictions on the
 
641
          form <c>Status</c> can take, but for
 
642
          the <c>sys:get_status/1,2</c> case (when <c>Opt</c>
 
643
          is <c>normal</c>), the recommended form for
 
644
          the <c>Status</c> value is <c>[{data, [{"State",
 
645
          Term}]}]</c> where <c>Term</c> provides relevant details of
 
646
          the gen_server state. Following this recommendation isn't
 
647
          required, but doing so will make the callback module status
 
648
          consistent with the rest of the <c>sys:get_status/1,2</c>
 
649
          return value.</p>
 
650
        <p>One use for this function is to return compact alternative
 
651
          state representations to avoid having large state terms
 
652
          printed in logfiles.</p>
 
653
      </desc>
 
654
    </func>
601
655
  </funcs>
602
656
 
603
657
  <section>