蚂蚁快跑

MiniGui

2008-05-06T19:29:00.001-07:00

一个用于嵌入式开发的GUI库，官方网站是http://www.minigui.org/

有空了解一下

ejabberd源码阅读笔记

2008-04-01T01:00:00.001-07:00

ejabberd_sup

ejabberd_sup是ejabberd的进程监视者()，由ejabberd_app创建。

supervisor(监视进程)

supervisor的功能是启动，停止和监控它的子进程。其作用是保持其子进程运行，在必要的时候重启其子进程，例如子进程死掉的时候。

A supervisor is responsible for starting, stopping and monitoring its child processes. The basic idea of a supervisor is that it should keep its child processes alive by restarting them when necessary.

ejabberd_sup负责创建一堆的子进程并监视它们，这些进程有:

ejabberd_hooks,ejabberd_node_groups,ejabberd_system_monitor,ejabberd_router,ejabberd_sm,ejabberd_s2s,ejabberd_local,

ejabberd_listener,ejabberd_receiver_sup,ejabberd_c2s_sup,ejabberd_s2s_in_sup,ejabberd_s2s_out_sup,ejabberd_service_sup,

ejabberd_http_sup,ejabberd_http_poll_sup,ejabberd_frontend_socket_sup,ejabberd_iq_sup,ejabberd_tmp_sup

这些进程大部分也是以sup结尾的supervisor监视进程.

ejabberd_listener

ejabberd_listener是由ejabberd_sup创建的一个supervisor进程，他负责监视和创建一系列的网络端口监听进程。

ejabberd_listener创建的端口监听进程列表是由配置文件中的listen读取的，配置文件样例如下:

{listen,
[
{4222, ejabberd_c2s, [
                        %%
                        %% If TLS is compiled and you installed a SSL
                        %% certificate, put the correct path to the
                        %% file and uncomment this line:
                        %%
                        %%{certfile, "/path/to/ssl.pem"}, starttls,
                        {access, c2s},
                        {shaper, c2s_shaper},
                        {max_stanza_size, 65536}
                       ]},

{5269, ejabberd_s2s_in, [
                          {shaper, s2s_shaper},
                          {max_stanza_size, 131072}
                         ]},

{5280, ejabberd_http, [
                        http_poll,
                        web_admin,
                        {request_handlers, [{["httpbind"], mod_http_bind},{["pub", "archive"], mod_http_fileserver}]}
                       ]},
{5347, ejabberd_service, [{host, "msn-transport.bucc.cn", [{password, "1j5llz!o"}]}]}
]}.

每个进程的格式如下,{port_no,module_name,[args]}

port_no:端口号，同时也是创建进程时的进程标识

module_name:进程模块名称

args:参数列表

ejabberd_receiver

ejabberd_receiver是一个gen_server进程(behaviour)，由ejabberd_socket创建

xml_stream

ejabber_c2s

ejabber_cs2是一个gen_fsm(有限状态机)，维护一系列client和server之间的状态。gen_fsm的状态改变是由gen_fsm:send_event(FsmRef, Event)触发的。在ejabberd里，ejabberd_receiver通过xml_stream把事件和xml发送至ejabber_c2s改变其状态。

ejabber_c2s有限状态机的初始状态是wait_for_stream,其余的状态有：

wait_for_auth,wait_for_feature_request,wait_for_sasl_response,wait_for_bind,wait_for_session,session_established

关于帐户免域登录：

将来如果需要添加这个功能，可以修改在ejabberd_c2s的代码实现这个功能，在wait_for_stream状态时，在给客户端发送stream:features的时候附上域名，这样客户端就可以登录的时候附上取得的域了，或者是直接在ejabberd_auth模块实现这个功能?

ejabbrd-XML Representation

2008-03-31T22:07:00.001-07:00

XML Representation

Each XML stanza is represented as the following tuple:

XMLElement = {xmlelement, Name, Attrs, [ElementOrCDATA]}
        Name = string()
        Attrs = [Attr]
        Attr = {Key, Val}
        Key = string()
        Val = string()
        ElementOrCDATA = XMLElement | CDATA
        CDATA = {xmlcdata, string()}

E. g. this stanza:

<message to='test@conference.example.org' type='groupchat'>
  <body>test</body>
</message>

is represented as the following structure:

{xmlelement, "message",
    [{"to", "test@conference.example.org"},
     {"type", "groupchat"}],
    [{xmlelement, "body",
         [],
         [{xmlcdata, "test"}]}]}}

ejabberd源码阅读笔记

2008-03-31T22:06:00.003-07:00

ejabberd_sup

ejabberd_sup是ejabberd的进程监视者()，由ejabberd_app创建。

supervisor(监视进程)

supervisor的功能是启动，停止和监控它的子进程。其作用是保持其子进程运行，在必要的时候重启其子进程，例如子进程死掉的时候。

ejabberd_sup负责创建一堆的子进程并监视它们，这些进程有:

ejabberd_hooks,ejabberd_node_groups,ejabberd_system_monitor,ejabberd_router,ejabberd_sm,ejabberd_s2s,ejabberd_local,

ejabberd_listener,ejabberd_receiver_sup,ejabberd_c2s_sup,ejabberd_s2s_in_sup,ejabberd_s2s_out_sup,ejabberd_service_sup,

ejabberd_http_sup,ejabberd_http_poll_sup,ejabberd_frontend_socket_sup,ejabberd_iq_sup,ejabberd_tmp_sup

这些进程大部分也是以sup结尾的supervisor监视进程.

ejabberd_listener

ejabberd_listener是由ejabberd_sup创建的一个supervisor进程，他负责监视和创建一系列的网络端口监听进程。

ejabberd_listener创建的端口监听进程列表是由配置文件中的listen读取的，配置文件样例如下:

{5269, ejabberd_s2s_in, [
                          {shaper, s2s_shaper},
                          {max_stanza_size, 131072}
                         ]},

每个进程的格式如下,{port_no,module_name,[args]}

port_no:端口号，同时也是创建进程时的进程标识

module_name:进程模块名称

args:参数列表

ejabberd_receiver

ejabberd_receiver是一个gen_server进程(behaviour)，由ejabberd_socket创建

xml_stream

ejabber_c2s

ejabber_c2s有限状态机的初始状态是wait_for_stream,其余的状态有：

wait_for_auth,wait_for_feature_request,wait_for_sasl_response,wait_for_bind,wait_for_session,session_established

erlang-gen_fsm

2008-03-31T22:06:00.001-07:00

MODULE

gen_fsm

MODULE SUMMARY

Generic Finite State Machine Behaviour

DESCRIPTION

A behaviour module for implementing a finite state machine. A generic finite state machine process (gen_fsm) implemented using this module will have a standard set of interface functions and include functionality for tracing and error reporting. It will also fit into an OTP supervision tree. Refer to OTP Design Principles for more information.

A gen_fsm assumes all specific parts to be located in a callback module exporting a pre-defined set of functions. The relationship between the behaviour functions and the callback functions can be illustrated as follows:

gen_fsm module                    Callback module
--------------                    ---------------
gen_fsm:start_link                -----> Module:init/1

gen_fsm:send_event                -----> Module:StateName/2

gen_fsm:send_all_state_event      -----> Module:handle_event/3

gen_fsm:sync_send_event           -----> Module:StateName/3

gen_fsm:sync_send_all_state_event -----> Module:handle_sync_event/4

-                                 -----> Module:handle_info/3

-                                 -----> Module:terminate/3

-                                 -----> Module:code_change/4

If a callback function fails or returns a bad value, the gen_fsm will terminate.

The sys module can be used for debugging a gen_fsm.

Note that a gen_fsm does not trap exit signals automatically, this must be explicitly initiated in the callback module.

Unless otherwise stated, all functions in this module fail if the specified gen_fsm does not exist or if bad arguments are given.

The gen_fsm process can go into hibernation (see erlang(3)) if a callback function specifies 'hibernate' instead of a timeout value. This might be useful if the server is expected to be idle for a long time. However this feature should be used with care as hibernation implies at least two garbage collections (when hibernating and shortly after waking up) and is not something you'd want to do between each call to a busy state machine.

EXPORTS

start_link(Module, Args, Options) -> Result

start_link(FsmName, Module, Args, Options) -> Result

Types:

FsmName = {local,Name} | {global,GlobalName}

Name = atom()

GlobalName = term()

Module = atom()

Args = term()

Options = [Option]

Option = {debug,Dbgs} | {timeout,Time} | {spawn_opt,SOpts}

Dbgs = [Dbg]

   Dbg = trace | log | statistics

    | {log_to_file,FileName} | {install,{Func,FuncState}}

SOpts = [SOpt]

   SOpt - see erlang:spawn_opt/2,3,4,5

Result = {ok,Pid} | ignore | {error,Error}

Pid = pid()

Error = {already_started,Pid} | term()

Creates a gen_fsm process as part of a supervision tree. The function should be called, directly or indirectly, by the supervisor. It will, among other things, ensure that the gen_fsm is linked to the supervisor.

The gen_fsm process calls Module:init/1 to initialize. To ensure a synchronized start-up procedure, start_link/3,4 does not return until Module:init/1 has returned.

If FsmName={local,Name}, the gen_fsm is registered locally as Name using register/2. If FsmName={global,GlobalName}, the gen_fsm is registered globally as GlobalName using global:register_name/2. If no name is provided, the gen_fsm is not registered.

Module is the name of the callback module.

Args is an arbitrary term which is passed as the argument to Module:init/1.

If the option {timeout,Time} is present, the gen_fsm is allowed to spend Time milliseconds initializing or it will be terminated and the start function will return {error,timeout}.

If the option {debug,Dbgs} is present, the corresponding sys function will be called for each item in Dbgs. See sys(3).

If the option {spawn_opt,SOpts} is present, SOpts will be passed as option list to the spawn_opt BIF which is used to spawn the gen_fsm process. See erlang(3).

Note

Using the spawn option monitor is currently not allowed, but will cause the function to fail with reason badarg.

If the gen_fsm is successfully created and initialized the function returns {ok,Pid}, where Pid is the pid of the gen_fsm. If there already exists a process with the specified FsmName, the function returns {error,{already_started,Pid}} where Pid is the pid of that process.

If Module:init/1 fails with Reason, the function returns {error,Reason}. If Module:init/1 returns {stop,Reason} or ignore, the process is terminated and the function returns {error,Reason} or ignore, respectively.

start(Module, Args, Options) -> Result

start(FsmName, Module, Args, Options) -> Result

Types:

FsmName = {local,Name} | {global,GlobalName}

Name = atom()

GlobalName = term()

Module = atom()

Args = term()

Options = [Option]

Option = {debug,Dbgs} | {timeout,Time} | {spawn_opt,SOpts}

Dbgs = [Dbg]

Dbg = trace | log | statistics

| {log_to_file,FileName} | {install,{Func,FuncState}}

SOpts = [term()]

Result = {ok,Pid} | ignore | {error,Error}

Pid = pid()

Error = {already_started,Pid} | term()

Creates a stand-alone gen_fsm process, i.e. a gen_fsm which is not part of a supervision tree and thus has no supervisor.

See start_link/3,4 for a description of arguments and return values.

send_event(FsmRef, Event) -> ok

Types:

FsmRef = Name | {Name,Node} | {global,GlobalName} | pid()

Name = Node = atom()

GlobalName = term()

Event = term()

Sends an event asynchronously to the gen_fsm FsmRef and returns ok immediately. The gen_fsm will call Module:StateName/2 to handle the event, where StateName is the name of the current state of the gen_fsm.

FsmRef can be:

the pid,

Name, if the gen_fsm is locally registered,

{Name,Node}, if the gen_fsm is locally registered at another node, or

{global,GlobalName}, if the gen_fsm is globally registered.

Event is an arbitrary term which is passed as one of the arguments to Module:StateName/2.

send_all_state_event(FsmRef, Event) -> ok

Types:

FsmRef = Name | {Name,Node} | {global,GlobalName} | pid()

Name = Node = atom()

GlobalName = term()

Event = term()

Sends an event asynchronously to the gen_fsm FsmRef and returns ok immediately. The gen_fsm will call Module:handle_event/3 to handle the event.

See send_event/2 for a description of the arguments.

The difference between send_event and send_all_state_event is which callback function is used to handle the event. This function is useful when sending events that are handled the same way in every state, as only one handle_event clause is needed to handle the event instead of one clause in each state name function.

sync_send_event(FsmRef, Event) -> Reply

sync_send_event(FsmRef, Event, Timeout) -> Reply

Types:

FsmRef = Name | {Name,Node} | {global,GlobalName} | pid()

Name = Node = atom()

GlobalName = term()

Event = term()

Timeout = int()>0 | infinity

Reply = term()

Sends an event to the gen_fsm FsmRef and waits until a reply arrives or a timeout occurs. The gen_fsm will call Module:StateName/3 to handle the event, where StateName is the name of the current state of the gen_fsm.

See send_event/2 for a description of FsmRef and Event.

Timeout is an integer greater than zero which specifies how many milliseconds to wait for a reply, or the atom infinity to wait indefinitely. Default value is 5000. If no reply is received within the specified time, the function call fails.

The return value Reply is defined in the return value of Module:StateName/3.

The ancient behaviour of sometimes consuming the server exit message if the server died during the call while linked to the client has been removed in OTP R12B/Erlang 5.6.

sync_send_all_state_event(FsmRef, Event) -> Reply

sync_send_all_state_event(FsmRef, Event, Timeout) -> Reply

Types:

FsmRef = Name | {Name,Node} | {global,GlobalName} | pid()

Name = Node = atom()

GlobalName = term()

Event = term()

Timeout = int()>0 | infinity

Reply = term()

Sends an event to the gen_fsm FsmRef and waits until a reply arrives or a timeout occurs. The gen_fsm will call Module:handle_sync_event/4 to handle the event.

See send_event/2 for a description of FsmRef and Event. See sync_send_event/3 for a description of Timeout and Reply.

See send_all_state_event/2 for a discussion about the difference between sync_send_event and sync_send_all_state_event.

reply(Caller, Reply) -> true

Types:

Caller - see below

Reply = term()

This function can be used by a gen_fsm to explicitly send a reply to a client process that called sync_send_event/2,3 or sync_send_all_state_event/2,3, when the reply cannot be defined in the return value of Module:State/3 or Module:handle_sync_event/4.

Caller must be the From argument provided to the callback function. Reply is an arbitrary term, which will be given back to the client as the return value of sync_send_event/2,3 or sync_send_all_state_event/2,3.

send_event_after(Time, Event) -> Ref

Types:

Time = integer()

Event = term()

Ref = reference()

Sends a delayed event internally in the gen_fsm that calls this function after Time ms. Returns immediately a reference that can be used to cancel the delayed send using cancel_timer/1.

The gen_fsm will call Module:StateName/2 to handle the event, where StateName is the name of the current state of the gen_fsm at the time the delayed event is delivered.

Event is an arbitrary term which is passed as one of the arguments to Module:StateName/2.

start_timer(Time, Msg) -> Ref

Types:

Time = integer()

Msg = term()

Ref = reference()

Sends a timeout event internally in the gen_fsm that calls this function after Time ms. Returns immediately a reference that can be used to cancel the timer using cancel_timer/1.

The gen_fsm will call Module:StateName/2 to handle the event, where StateName is the name of the current state of the gen_fsm at the time the timeout message is delivered.

Msg is an arbitrary term which is passed in the timeout message, {timeout, Ref, Msg}, as one of the arguments to Module:StateName/2.

cancel_timer(Ref) -> RemainingTime | false

Types:

Ref = reference()

RemainingTime = integer()

Cancels an internal timer referred by Ref in the gen_fsm that calls this function.

Ref is a reference returned from send_event_after/2 or start_timer/2.

If the timer has already timed out, but the event not yet been delivered, it is cancelled as if it had not timed out, so there will be no false timer event after returning from this function.

Returns the remaining time in ms until the timer would have expired if Ref referred to an active timer, false otherwise.

enter_loop(Module, Options, StateName, StateData)

enter_loop(Module, Options, StateName, StateData, FsmName)

enter_loop(Module, Options, StateName, StateData, Timeout)

enter_loop(Module, Options, StateName, StateData, FsmName, Timeout)

Types:

Module = atom()

Options = [Option]

Option = {debug,Dbgs}

Dbgs = [Dbg]

Dbg = trace | log | statistics

| {log_to_file,FileName} | {install,{Func,FuncState}}

StateName = atom()

StateData = term()

FsmName = {local,Name} | {global,GlobalName}

Name = atom()

GlobalName = term()

Timeout = int() | infinity

Makes an existing process into a gen_fsm. Does not return, instead the calling process will enter the gen_fsm receive loop and become a gen_fsm process. The process must have been started using one of the start functions in proc_lib, see proc_lib(3). The user is responsible for any initialization of the process, including registering a name for it.

This function is useful when a more complex initialization procedure is needed than the gen_fsm behaviour provides.

Module, Options and FsmName have the same meanings as when calling start[_link]/3,4. However, if FsmName is specified, the process must have been registered accordingly before this function is called.

StateName, StateData and Timeout have the same meanings as in the return value of Module:init/1. Also, the callback module Module does not need to export an init/1 function.

Failure: If the calling process was not started by a proc_lib start function, or if it is not registered according to FsmName.

CALLBACK FUNCTIONS

The following functions should be exported from a gen_fsm callback module.

In the description, the expression state name is used to denote a state of the state machine. state data is used to denote the internal state of the Erlang process which implements the state machine.

EXPORTS

Module:init(Args) -> Result

Types:

Args = term()

Return = {ok,StateName,StateData} | {ok,StateName,StateData,Timeout}

| {ok,StateName,StateData,hibernate}

| {stop,Reason} | ignore

StateName = atom()

StateData = term()

Timeout = int()>0 | infinity

Reason = term()

Whenever a gen_fsm is started using gen_fsm:start/3,4 or gen_fsm:start_link/3,4, this function is called by the new process to initialize.

Args is the Args argument provided to the start function.

If initialization is successful, the function should return {ok,StateName,StateData}, {ok,StateName,StateData,Timeout} or {ok,StateName,StateData,hibernate}, where StateName is the initial state name and StateData the initial state data of the gen_fsm.

If an integer timeout value is provided, a timeout will occur unless an event or a message is received within Timeout milliseconds. A timeout is represented by the atom timeout and should be handled by the Module:StateName/2 callback functions. The atom infinity can be used to wait indefinitely, this is the default value.

If hibernate is specified instead of a timeout value, the process will go into hibernation when waiting for the next message to arrive (by calling proc_lib:hibernate/3).

If something goes wrong during the initialization the function should return {stop,Reason}, where Reason is any term, or ignore.

Module:StateName(Event, StateData) -> Result

Types:

Event = timeout | term()

StateData = term()

Result = {next_state,NextStateName,NewStateData}

| {next_state,NextStateName,NewStateData,Timeout}

| {next_state,NextStateName,NewStateData,hibernate}

| {stop,Reason,NewStateData}

NextStateName = atom()

NewStateData = term()

Timeout = int()>0 | infinity

Reason = term()

There should be one instance of this function for each possible state name. Whenever a gen_fsm receives an event sent using gen_fsm:send_event/2, the instance of this function with the same name as the current state name StateName is called to handle the event. It is also called if a timeout occurs.

Event is either the atom timeout, if a timeout has occurred, or the Event argument provided to send_event/2.

StateData is the state data of the gen_fsm.

If the function returns {next_state,NextStateName,NewStateData}, {next_state,NextStateName,NewStateData,Timeout} or {next_state,NextStateName,NewStateData,hibernate}, the gen_fsm will continue executing with the current state name set to NextStateName and with the possibly updated state data NewStateData. See Module:init/1 for a description of Timeout and hibernate.

If the function returns {stop,Reason,NewStateData}, the gen_fsm will call Module:terminate(Reason,NewStateData) and terminate.

Module:handle_event(Event, StateName, StateData) -> Result

Types:

Event = term()

StateName = atom()

StateData = term()

Result = {next_state,NextStateName,NewStateData}

| {next_state,NextStateName,NewStateData,Timeout}

| {next_state,NextStateName,NewStateData,hibernate}

| {stop,Reason,NewStateData}

NextStateName = atom()

NewStateData = term()

Timeout = int()>0 | infinity

Reason = term()

Whenever a gen_fsm receives an event sent using gen_fsm:send_all_state_event/2, this function is called to handle the event.

StateName is the current state name of the gen_fsm.

See Module:StateName/2 for a description of the other arguments and possible return values.

Module:StateName(Event, From, StateData) -> Result

Types:

Event = term()

From = {pid(),Tag}

StateData = term()

Result = {reply,Reply,NextStateName,NewStateData}

| {reply,Reply,NextStateName,NewStateData,Timeout}

| {reply,Reply,NextStateName,NewStateData,hibernate}

| {next_state,NextStateName,NewStateData}

| {next_state,NextStateName,NewStateData,Timeout}

| {next_state,NextStateName,NewStateData,hibernate}

| {stop,Reason,Reply,NewStateData} | {stop,Reason,NewStateData}

Reply = term()

NextStateName = atom()

NewStateData = term()

Timeout = int()>0 | infinity

Reason = normal | term()

There should be one instance of this function for each possible state name. Whenever a gen_fsm receives an event sent using gen_fsm:sync_send_event/2,3, the instance of this function with the same name as the current state name StateName is called to handle the event.

Event is the Event argument provided to sync_send_event.

From is a tuple {Pid,Tag} where Pid is the pid of the process which called sync_send_event/2,3 and Tag is a unique tag.

StateData is the state data of the gen_fsm.

If the function returns {reply,Reply,NextStateName,NewStateData}, {reply,Reply,NextStateName,NewStateData,Timeout} or {reply,Reply,NextStateName,NewStateData,hibernate}, Reply will be given back to From as the return value of sync_send_event/2,3. The gen_fsm then continues executing with the current state name set to NextStateName and with the possibly updated state data NewStateData. See Module:init/1 for a description of Timeout and hibernate.

If the function returns {next_state,NextStateName,NewStateData}, {next_state,NextStateName,NewStateData,Timeout} or {next_state,NextStateName,NewStateData,hibernate}, the gen_fsm will continue executing in NextStateName with NewStateData. Any reply to From must be given explicitly using gen_fsm:reply/2.

If the function returns {stop,Reason,Reply,NewStateData}, Reply will be given back to From. If the function returns {stop,Reason,NewStateData}, any reply to From must be given explicitly using gen_fsm:reply/2. The gen_fsm will then call Module:terminate(Reason,NewStateData) and terminate.

Module:handle_sync_event(Event, From, StateName, StateData) -> Result

Types:

Event = term()

From = {pid(),Tag}

StateName = atom()

StateData = term()

Result = {reply,Reply,NextStateName,NewStateData}

| {reply,Reply,NextStateName,NewStateData,Timeout}

| {reply,Reply,NextStateName,NewStateData,hibernate}

| {next_state,NextStateName,NewStateData}

| {next_state,NextStateName,NewStateData,Timeout}

| {next_state,NextStateName,NewStateData,hibernate}

| {stop,Reason,Reply,NewStateData} | {stop,Reason,NewStateData}

Reply = term()

NextStateName = atom()

NewStateData = term()

Timeout = int()>0 | infinity

Reason = term()

Whenever a gen_fsm receives an event sent using gen_fsm:sync_send_all_state_event/2,3, this function is called to handle the event.

StateName is the current state name of the gen_fsm.

See Module:StateName/3 for a description of the other arguments and possible return values.

Module:handle_info(Info, StateName, StateData) -> Result

Types:

Info = term()

StateName = atom()

StateData = term()

Result = {next_state,NextStateName,NewStateData}

> | {next_state,NextStateName,NewStateData,Timeout}

> | {next_state,NextStateName,NewStateData,hibernate}

> | {stop,Reason,NewStateData}

NextStateName = atom()

NewStateData = term()

Timeout = int()>0 | infinity

Reason = normal | term()

This function is called by a gen_fsm when it receives any other message than a synchronous or asynchronous event (or a system message).

Info is the received message.

See Module:StateName/2 for a description of the other arguments and possible return values.

Module:terminate(Reason, StateName, StateData)

Types:

Reason = normal | shutdown | term()

StateName = atom()

StateData = term()

This function is called by a gen_fsm when it is about to terminate. It should be the opposite of Module:init/1 and do any necessary cleaning up. When it returns, the gen_fsm terminates with Reason. The return value is ignored.

Reason is a term denoting the stop reason, StateName is the current state name, and StateData is the state data of the gen_fsm.

Reason depends on why the gen_fsm is terminating. If it is because another callback function has returned a stop tuple {stop,..}, Reason will have the value specified in that tuple. If it is due to a failure, Reason is the error reason.

If the gen_fsm is part of a supervision tree and is ordered by its supervisor to terminate, this function will be called with Reason=shutdown if the following conditions apply:

the gen_fsm has been set to trap exit signals, and

the shutdown strategy as defined in the supervisor's child specification is an integer timeout value, not brutal_kill.

Otherwise, the gen_fsm will be immediately terminated.

Note that for any other reason than normal or shutdown, the gen_fsm is assumed to terminate due to an error and an error report is issued using error_logger:format/2.

Module:code_change(OldVsn, StateName, StateData, Extra) -> {ok, NextStateName, NewStateData}

Types:

OldVsn = Vsn | {down, Vsn}

Vsn = term()

StateName = NextStateName = atom()

StateData = NewStateData = term()

Extra = term()

This function is called by a gen_fsm when it should update its internal state data during a release upgrade/downgrade, i.e. when the instruction {update,Module,Change,...} where Change={advanced,Extra} is given in the appup file. See OTP Design Principles.

In the case of an upgrade, OldVsn is Vsn, and in the case of a downgrade, OldVsn is {down,Vsn}. Vsn is defined by the vsn attribute(s) of the old version of the callback module Module. If no such attribute is defined, the version is the checksum of the BEAM file.

StateName is the current state name and StateData the internal state data of the gen_fsm.

Extra is passed as-is from the {advanced,Extra} part of the update instruction.

The function should return the new current state name and updated internal data.

gen_server

2008-03-31T22:05:00.001-07:00

MODULE

gen_server

MODULE SUMMARY

Generic Server Behaviour

DESCRIPTION

A behaviour module for implementing the server of a client-server relation. A generic server process (gen_server) implemented using this module will have a standard set of interface functions and include functionality for tracing and error reporting. It will also fit into an OTP supervision tree. Refer to OTP Design Principles for more information.

A gen_server assumes all specific parts to be located in a callback module exporting a pre-defined set of functions. The relationship between the behaviour functions and the callback functions can be illustrated as follows:

gen_server module            Callback module
-----------------            ---------------
gen_server:start_link -----> Module:init/1

gen_server:call
gen_server:multi_call -----> Module:handle_call/3

gen_server:cast
gen_server:abcast     -----> Module:handle_cast/2

-                     -----> Module:handle_info/2

-                     -----> Module:terminate/2

-                     -----> Module:code_change/3

If a callback function fails or returns a bad value, the gen_server will terminate.

The sys module can be used for debugging a gen_server.

Note that a gen_server does not trap exit signals automatically, this must be explicitly initiated in the callback module.

Unless otherwise stated, all functions in this module fail if the specified gen_server does not exist or if bad arguments are given.

The gen_server process can go into hibernation (see erlang(3)) if a callback function specifies 'hibernate' instead of a timeout value. This might be useful if the server is expected to be idle for a long time. However this feature should be used with care as hibernation implies at least two garbage collections (when hibernating and shortly after waking up) and is not something you'd want to do between each call to a busy server.

EXPORTS

start_link(Module, Args, Options) -> Result

start_link(ServerName, Module, Args, Options) -> Result

Types:

ServerName = {local,Name} | {global,GlobalName}

Name = atom()

GlobalName = term()

Module = atom()

Args = term()

Options = [Option]

Option = {debug,Dbgs} | {timeout,Time} | {spawn_opt,SOpts}

Dbgs = [Dbg]

Dbg = trace | log | statistics | {log_to_file,FileName} | {install,{Func,FuncState}}

SOpts = [term()]

Result = {ok,Pid} | ignore | {error,Error}

Pid = pid()

Error = {already_started,Pid} | term()

Creates a gen_server process as part of a supervision tree. The function should be called, directly or indirectly, by the supervisor. It will, among other things, ensure that the gen_server is linked to the supervisor.

The gen_server process calls Module:init/1 to initialize. To ensure a synchronized start-up procedure, start_link/3,4 does not return until Module:init/1 has returned.

If ServerName={local,Name} the gen_server is registered locally as Name using register/2. If ServerName={global,GlobalName} the gen_server is registered globally as GlobalName using global:register_name/2. If no name is provided, the gen_server is not registered.

Module is the name of the callback module.

Args is an arbitrary term which is passed as the argument to Module:init/1.

If the option {timeout,Time} is present, the gen_server is allowed to spend Time milliseconds initializing or it will be terminated and the start function will return {error,timeout}.

If the option {debug,Dbgs} is present, the corresponding sys function will be called for each item in Dbgs. See sys(3).

If the option {spawn_opt,SOpts} is present, SOpts will be passed as option list to the spawn_opt BIF which is used to spawn the gen_server. See erlang(3).

Note

Using the spawn option monitor is currently not allowed, but will cause the function to fail with reason badarg.

If the gen_server is successfully created and initialized the function returns {ok,Pid}, where Pid is the pid of the gen_server. If there already exists a process with the specified ServerName the function returns {error,{already_started,Pid}}, where Pid is the pid of that process.

start(Module, Args, Options) -> Result

start(ServerName, Module, Args, Options) -> Result

Types:

Creates a stand-alone gen_server process, i.e. a gen_server which is not part of a supervision tree and thus has no supervisor.

See start_link/3,4 for a description of arguments and return values.

call(ServerRef, Request) -> Reply

call(ServerRef, Request, Timeout) -> Reply

Types:

ServerRef = Name | {Name,Node} | {global,GlobalName} | pid()

Node = atom()

GlobalName = term()

Request = term()

Timeout = int()>0 | infinity

Reply = term()

Makes a synchronous call to the gen_server ServerRef by sending a request and waiting until a reply arrives or a timeout occurs. The gen_server will call Module:handle_call/3 to handle the request.

ServerRef can be:

the pid,

Name, if the gen_server is locally registered,

{Name,Node}, if the gen_server is locally registered at another node, or

{global,GlobalName}, if the gen_server is globally registered.

Request is an arbitrary term which is passed as one of the arguments to Module:handle_call/3.

The return value Reply is defined in the return value of Module:handle_call/3.

The call may fail for several reasons, including timeout and the called gen_server dying before or during the call.

The ancient behaviour of sometimes consuming the server exit message if the server died during the call while linked to the client has been removed in OTP R12B/Erlang 5.6.

multi_call(Name, Request) -> Result

multi_call(Nodes, Name, Request) -> Result

multi_call(Nodes, Name, Request, Timeout) -> Result

Types:

Nodes = [Node]

Node = atom()

Name = atom()

Request = term()

Timeout = int()>=0 | infinity

Result = {Replies,BadNodes}

Replies = [{Node,Reply}]

Reply = term()

BadNodes = [Node]

Makes a synchronous call to all gen_servers locally registered as Name at the specified nodes by first sending a request to every node and then waiting for the replies. The gen_servers will call Module:handle_call/3 to handle the request.

The function returns a tuple {Replies,BadNodes} where Replies is a list of {Node,Reply} and BadNodes is a list of node that either did not exist, or where the gen_server Name did not exist or did not reply.

Nodes is a list of node names to which the request should be sent. Default value is the list of all known nodes [node()|nodes()].

Name is the locally registered name of each gen_server.

Request is an arbitrary term which is passed as one of the arguments to Module:handle_call/3.

Timeout is an integer greater than zero which specifies how many milliseconds to wait for each reply, or the atom infinity to wait indefinitely. Default value is infinity. If no reply is received from a node within the specified time, the node is added to BadNodes.

When a reply Reply is received from the gen_server at a node Node, {Node,Reply} is added to Replies. Reply is defined in the return value of Module:handle_call/3.

Warning

If one of the nodes is not capable of process monitors, for example C or Java nodes, and the gen_server is not started when the requests are sent, but starts within 2 seconds, this function waits the whole Timeout, which may be infinity.

This problem does not exist if all nodes are Erlang nodes.

To avoid that late answers (after the timeout) pollutes the caller's message queue, a middleman process is used to do the actual calls. Late answers will then be discarded when they arrive to a terminated process.

cast(ServerRef, Request) -> ok

Types:

ServerRef = Name | {Name,Node} | {global,GlobalName} | pid()

Node = atom()

GlobalName = term()

Request = term()

Sends an asynchronous request to the gen_server ServerRef and returns ok immediately, ignoring if the destination node or gen_server does not exist. The gen_server will call Module:handle_cast/2 to handle the request.

See call/2,3 for a description of ServerRef.

Request is an arbitrary term which is passed as one of the arguments to Module:handle_cast/2.

abcast(Name, Request) -> abcast

abcast(Nodes, Name, Request) -> abcast

Types:

Nodes = [Node]

Node = atom()

Name = atom()

Request = term()

Sends an asynchronous request to the gen_servers locally registered as Name at the specified nodes. The function returns immediately and ignores nodes that do not exist, or where the gen_server Name does not exist. The gen_servers will call Module:handle_cast/2 to handle the request.

See multi_call/2,3,4 for a description of the arguments.

reply(Client, Reply) -> Result

Types:

Client - see below

Reply = term()

Result = term()

This function can be used by a gen_server to explicitly send a reply to a client that called call/2,3 or multi_call/2,3,4, when the reply cannot be defined in the return value of Module:handle_call/3.

Client must be the From argument provided to the callback function. Reply is an arbitrary term, which will be given back to the client as the return value of call/2,3 or multi_call/2,3,4.

The return value Result is not further defined, and should always be ignored.

enter_loop(Module, Options, State)

enter_loop(Module, Options, State, ServerName)

enter_loop(Module, Options, State, Timeout)

enter_loop(Module, Options, State, ServerName, Timeout)

Types:

Module = atom()

Options = [Option]

Option = {debug,Dbgs}

Dbgs = [Dbg]

Dbg = trace | log | statistics

| {log_to_file,FileName} | {install,{Func,FuncState}}

State = term()

ServerName = {local,Name} | {global,GlobalName}

Name = atom()

GlobalName = term()

Timeout = int() | infinity

Makes an existing process into a gen_server. Does not return, instead the calling process will enter the gen_server receive loop and become a gen_server process. The process must have been started using one of the start functions in proc_lib, see proc_lib(3). The user is responsible for any initialization of the process, including registering a name for it.

This function is useful when a more complex initialization procedure is needed than the gen_server behaviour provides.

Module, Options and ServerName have the same meanings as when calling gen_server:start[_link]/3,4. However, if ServerName is specified, the process must have been registered accordingly before this function is called.

State and Timeout have the same meanings as in the return value of Module:init/1. Also, the callback module Module does not need to export an init/1 function.

Failure: If the calling process was not started by a proc_lib start function, or if it is not registered according to ServerName.

CALLBACK FUNCTIONS

The following functions should be exported from a gen_server callback module.

EXPORTS

Module:init(Args) -> Result

Types:

Args = term()

Result = {ok,State} | {ok,State,Timeout} | {ok,State,hibernate}

| {stop,Reason} | ignore

State = term()

Timeout = int()>=0 | infinity

Reason = term()

Whenever a gen_server is started using gen_server:start/3,4 or gen_server:start_link/3,4, this function is called by the new process to initialize.

Args is the Args argument provided to the start function.

If the initialization is successful, the function should return {ok,State}, {ok,State,Timeout} or {ok,State,hibernate}, where State is the internal state of the gen_server.

If an integer timeout value is provided, a timeout will occur unless a request or a message is received within Timeout milliseconds. A timeout is represented by the atom timeout which should be handled by the handle_info/2 callback function. The atom infinity can be used to wait indefinitely, this is the default value.

If hibernate is specified instead of a timeout value, the process will go into hibernation when waiting for the next message to arrive (by calling proc_lib:hibernate/3).

If something goes wrong during the initialization the function should return {stop,Reason} where Reason is any term, or ignore.

Module:handle_call(Request, From, State) -> Result

Types:

Request = term()

From = {pid(),Tag}

State = term()

Result = {reply,Reply,NewState} | {reply,Reply,NewState,Timeout}

| {reply,Reply,NewState,hibernate}

| {noreply,NewState} | {noreply,NewState,Timeout}

| {noreply,NewState,hibernate}

| {stop,Reason,Reply,NewState} | {stop,Reason,NewState}

Reply = term()

NewState = term()

Timeout = int()>=0 | infinity

Reason = term()

Whenever a gen_server receives a request sent using gen_server:call/2,3 or gen_server:multi_call/2,3,4, this function is called to handle the request.

Request is the Request argument provided to call or multi_call.

From is a tuple {Pid,Tag} where Pid is the pid of the client and Tag is a unique tag.

State is the internal state of the gen_server.

If the function returns {reply,Reply,NewState}, {reply,Reply,NewState,Timeout} or {reply,Reply,NewState,hibernate}, Reply will be given back to From as the return value of call/2,3 or included in the return value of multi_call/2,3,4. The gen_server then continues executing with the possibly updated internal state NewState. See Module:init/1 for a description of Timeout and hibernate.

If the functions returns {noreply,NewState}, {noreply,NewState,Timeout} or {noreply,NewState,hibernate}, the gen_server will continue executing with NewState. Any reply to From must be given explicitly using gen_server:reply/2.

If the function returns {stop,Reason,Reply,NewState}, Reply will be given back to From. If the function returns {stop,Reason,NewState}, any reply to From must be given explicitly using gen_server:reply/2. The gen_server will then call Module:terminate(Reason,NewState) and terminate.

Module:handle_cast(Request, State) -> Result

Types:

Request = term()

State = term()

Result = {noreply,NewState} | {noreply,NewState,Timeout}

| {noreply,NewState,hibernate}

| {stop,Reason,NewState}

NewState = term()

Timeout = int()>=0 | infinity

Reason = term()

Whenever a gen_server receives a request sent using gen_server:cast/2 or gen_server:abcast/2,3, this function is called to handle the request.

See Module:handle_call/3 for a description of the arguments and possible return values.

Module:handle_info(Info, State) -> Result

Types:

Info = timeout | term()

State = term()

Result = {noreply,NewState} | {noreply,NewState,Timeout}

| {noreply,NewState,hibernate}

| {stop,Reason,NewState}

NewState = term()

Timeout = int()>=0 | infinity

Reason = normal | term()

This function is called by a gen_server when a timeout occurs or when it receives any other message than a synchronous or asynchronous request (or a system message).

Info is either the atom timeout, if a timeout has occurred, or the received message.

See Module:handle_call/3 for a description of the other arguments and possible return values.

Module:terminate(Reason, State)

Types:

Reason = normal | shutdown | term()

State = term()

This function is called by a gen_server when it is about to terminate. It should be the opposite of Module:init/1 and do any necessary cleaning up. When it returns, the gen_server terminates with Reason. The return value is ignored.

Reason is a term denoting the stop reason and State is the internal state of the gen_server.

Reason depends on why the gen_server is terminating. If it is because another callback function has returned a stop tuple {stop,..}, Reason will have the value specified in that tuple. If it is due to a failure, Reason is the error reason.

If the gen_server is part of a supervision tree and is ordered by its supervisor to terminate, this function will be called with Reason=shutdown if the following conditions apply:

the gen_server has been set to trap exit signals, and

the shutdown strategy as defined in the supervisor's child specification is an integer timeout value, not brutal_kill.

Otherwise, the gen_server will be immediately terminated.

Note that for any other reason than normal or shutdown, the gen_server is assumed to terminate due to an error and an error report is issued using error_logger:format/2.

Module:code_change(OldVsn, State, Extra) -> {ok, NewState}

Types:

OldVsn = Vsn | {down, Vsn}

Vsn = term()

State = NewState = term()

Extra = term()

This function is called by a gen_server when it should update its internal state during a release upgrade/downgrade, i.e. when the instruction {update,Module,Change,...} where Change={advanced,Extra} is given in the appup file. See OTP Design Principles for more information.

State is the internal state of the gen_server.

Extra is passed as-is from the {advanced,Extra} part of the update instruction.

The function should return the updated internal state.

erlang-Supervisor Behaviour

2008-03-31T22:04:00.005-07:00

Supervisor Behaviour

This section should be read in conjunction with supervisor(3), where all details about the supervisor behaviour is given.

5.1 Supervision Principles

Which child processes to start and monitor is specified by a list of child specifications. The child processes are started in the order specified by this list, and terminated in the reversed order.

5.2 Example

The callback module for a supervisor starting the server from the gen_server chapter could look like this:

-module(ch_sup).
-behaviour(supervisor).

-export([start_link/0]).
-export([init/1]).

start_link() ->
    supervisor:start_link(ch_sup, []).

init(_Args) ->
    {ok, {{one_for_one, 1, 60},
          [{ch3, {ch3, start_link, []},
            permanent, brutal_kill, worker, [ch3]}]}}.

one_for_one is the restart strategy.

1 and 60 defines the maximum restart frequency.

The tuple {ch3, ...} is a child specification.

5.3 Restart Strategy

5.3.1 one_for_one

If a child process terminates, only that process is restarted.

One_For_One Supervision

5.3.2 one_for_all

If a child process terminates, all other child processes are terminated and then all child processes, including the terminated one, are restarted.

One_For_All Supervision

5.3.3 rest_for_one

If a child process terminates, the 'rest' of the child processes -- i.e. the child processes after the terminated process in start order -- are terminated. Then the terminated child process and the rest of the child processes are restarted.

5.4 Maximum Restart Frequency

The supervisors have a built-in mechanism to limit the number of restarts which can occur in a given time interval. This is determined by the values of the two parameters MaxR and MaxT in the start specification returned by the callback function init:

init(...) ->
    {ok, {{RestartStrategy, MaxR, MaxT},
          [ChildSpec, ...]}}.

If more than MaxR number of restarts occur in the last MaxT seconds, then the supervisor terminates all the child processes and then itself.

When the supervisor terminates, then the next higher level supervisor takes some action. It either restarts the terminated supervisor, or terminates itself.

The intention of the restart mechanism is to prevent a situation where a process repeatedly dies for the same reason, only to be restarted again.

5.5 Child Specification

This is the type definition for a child specification:

{Id, StartFunc, Restart, Shutdown, Type, Modules}
    Id = term()
    StartFunc = {M, F, A}
        M = F = atom()
        A = [term()]
    Restart = permanent | transient | temporary
    Shutdown = brutal_kill | integer() &gt;=0 | infinity
    Type = worker | supervisor
    Modules = [Module] | dynamic
        Module = atom()

Id is a name that is used to identify the child specification internally by the supervisor.

StartFunc defines the function call used to start the child process. It is a module-function-arguments tuple used as apply(M, F, A).

It should be (or result in) a call to supervisor:start_link, gen_server:start_link, gen_fsm:start_link or gen_event:start_link. (Or a function compliant with these functions, see supervisor(3) for details.

Restart defines when a terminated child process should be restarted.
- A permanent child process is always restarted.
- A temporary child process is never restarted.
- A transient child process is restarted only if it terminates abnormally, i.e. with another exit reason than normal.

Shutdown defines how a child process should be terminated.
- brutal_kill means the child process is unconditionally terminated using exit(Child, kill).
- An integer timeout value means that the supervisor tells the child process to terminate by calling exit(Child, shutdown) and then waits for an exit signal back. If no exit signal is received within the specified time, the child process is unconditionally terminated using exit(Child, kill).
- If the child process is another supervisor, it should be set to infinity to give the subtree enough time to shutdown.

Type specifies if the child process is a supervisor or a worker.

Modules should be a list with one element [Module], where Module is the name of the callback module, if the child process is a supervisor, gen_server or gen_fsm. If the child process is a gen_event, Modules should be dynamic.

This information is used by the release handler during upgrades and downgrades, see Release Handling.

Example: The child specification to start the server ch3 in the example above looks like:

{ch3,
 {ch3, start_link, []},
 permanent, brutal_kill, worker, [ch3]}

Example: A child specification to start the event manager from the chapter about gen_event:

{error_man,
 {gen_event, start_link, [{local, error_man}]},
 permanent, 5000, worker, dynamic}

Both the server and event manager are registered processes which can be expected to be accessible at all times, thus they are specified to be permanent.

ch3 does not need to do any cleaning up before termination, thus no shutdown time is needed but brutal_kill should be sufficient. error_man may need some time for the event handlers to clean up, thus Shutdown is set to 5000 ms.

Example: A child specification to start another supervisor:

{sup,
 {sup, start_link, []},
 transient, infinity, supervisor, [sup]}

5.6 Starting a Supervisor

In the example above, the supervisor is started by calling ch_sup:start_link():

start_link() ->
    supervisor:start_link(ch_sup, []).

ch_sup:start_link calls the function supervisor:start_link/2. This function spawns and links to a new process, a supervisor.

The first argument, ch_sup, is the name of the callback module, that is the module where the init callback function is located.

The second argument, [], is a term which is passed as-is to the callback function init. Here, init does not need any indata and ignores the argument.

In this case, the supervisor is not registered. Instead its pid must be used. A name can be specified by calling supervisor:start_link({local, Name}, Module, Args) or supervisor:start_link({global, Name}, Module, Args).

The new supervisor process calls the callback function ch_sup:init([]). init is expected to return {ok, StartSpec}:

init(_Args) ->
    {ok, {{one_for_one, 1, 60},
          [{ch3, {ch3, start_link, []},
            permanent, brutal_kill, worker, [ch3]}]}}.

The supervisor then starts all its child processes according to the child specifications in the start specification. In this case there is one child process, ch3.

Note that supervisor:start_link is synchronous. It does not return until all child processes have been started.

5.7 Adding a Child Process

In addition to the static supervision tree, we can also add dynamic child processes to an existing supervisor with the following call:

supervisor:start_child(Sup, ChildSpec)

Sup is the pid, or name, of the supervisor. ChildSpec is a child specification.

Child processes added using start_child/2 behave in the same manner as the other child processes, with the following important exception: If a supervisor dies and is re-created, then all child processes which were dynamically added to the supervisor will be lost.

5.8 Stopping a Child Process

Any child process, static or dynamic, can be stopped in accordance with the shutdown specification:

supervisor:terminate_child(Sup, Id)

The child specification for a stopped child process is deleted with the following call:

supervisor:delete_child(Sup, Id)

Sup is the pid, or name, of the supervisor. Id is the id specified in the child specification.

As with dynamically added child processes, the effects of deleting a static child process is lost if the supervisor itself restarts.

5.9 Simple-One-For-One Supervisors

A supervisor with restart strategy simple_one_for_one is a simplified one_for_one supervisor, where all child processes are dynamically added instances of the same process.

Example of a callback module for a simple_one_for_one supervisor:

-module(simple_sup).
-behaviour(supervisor).

-export([start_link/0]).
-export([init/1]).

start_link() ->
    supervisor:start_link(simple_sup, []).

init(_Args) ->
    {ok, {{simple_one_for_one, 0, 1},
          [{call, {call, start_link, []},
            temporary, brutal_kill, worker, [call]}]}}.

When started, the supervisor will not start any child processes. Instead, all child processes are added dynamically by calling:

supervisor:start_child(Sup, List)

Sup is the pid, or name, of the supervisor. List is an arbitrary list of terms which will be added to the list of arguments specified in the child specification. If the start function is specified as {M, F, A}, then the child process is started by calling apply(M, F, A++List).

For example, adding a child to simple_sup above:

supervisor:start_child(Pid, [id1])

results in the child process being started by calling apply(call, start_link, []++[id1]), or actually:

call:start_link(id1)

5.10 Stopping

Since the supervisor is part of a supervision tree, it will automatically be terminated by its supervisor. When asked to shutdown, it will terminate all child processes in reversed start order according to the respective shutdown specifications, and then terminate itself.

erlang之Module gen_fsm

2008-03-31T22:04:00.003-07:00

Module gen_fsm

有限状态机模块。

什么是有限状态机(FSM)？PS：唉，大学编译原理没学好，现在要补课

简述
有限状态机（以下用FSM指代）是一种算法思想，简单而言，有限状态机由一组状态、一个初始状态、输入和根据输入及现有状态转换为下一个状态的转换函数组成。

Gen_Fsm Behaviour

This chapter should be read in conjunction with gen_fsm(3), where all interface functions and callback functions are described in detail.

3.1 Finite State Machines

A finite state machine, FSM, can be described as a set of relations of the form:

State(S) x Event(E) -> Actions(A), State(S')

These relations are interpreted as meaning:

If we are in state S and the event E occurs, we should perform the actions A and make a transition to the state S'.

For an FSM implemented using the gen_fsm behaviour, the state transition rules are written as a number of Erlang functions which conform to the following convention:

StateName(Event, StateData) ->
    .. code for actions here ...
    {next_state, StateName', StateData'}

3.2 Example

A door with a code lock could be viewed as an FSM. Initially, the door is locked. Anytime someone presses a button, this generates an event. Depending on what buttons have been pressed before, the sequence so far may be correct, incomplete or wrong.

If it is correct, the door is unlocked for 30 seconds (30000 ms). If it is incomplete, we wait for another button to be pressed. If it is is wrong, we start all over, waiting for a new button sequence.

Implementing the code lock FSM using gen_fsm results in this callback module:

-module(code_lock).
-behaviour(gen_fsm).

-export([start_link/1]).
-export([button/1]).
-export([init/1, locked/2, open/2]).

start_link(Code) ->
    gen_fsm:start_link({local, code_lock}, code_lock, Code, []).

button(Digit) ->
    gen_fsm:send_event(code_lock, {button, Digit}).

init(Code) ->
    {ok, locked, {[], Code}}.

locked({button, Digit}, {SoFar, Code}) ->
    case [Digit|SoFar] of
        Code ->
            do_unlock(),
            {next_state, open, {[], Code}, 3000};
        Incomplete when length(Incomplete)<length(Code) ->
            {next_state, locked, {Incomplete, Code}};
        _Wrong ->
            {next_state, locked, {[], Code}};
    end.

open(timeout, State) ->
    do_lock(),
    {next_state, locked, State}.

The code is explained in the next sections.

3.3 Starting a Gen_Fsm

In the example in the previous section, the gen_fsm is started by calling code_lock:start_link(Code):

start_link(Code) ->
    gen_fsm:start_link({local, code_lock}, code_lock, Code, []).

start_link calls the function gen_fsm:start_link/4. This function spawns and links to a new process, a gen_fsm.

The first argument {local, code_lock} specifies the name. In this case, the gen_fsm will be locally registered as code_lock.

If the name is omitted, the gen_fsm is not registered. Instead its pid must be used. The name could also be given as {global, Name}, in which case the gen_fsm is registered using global:register_name/2.

The second argument, code_lock, is the name of the callback module, that is the module where the callback functions are located.

In this case, the interface functions (start_link and button) are located in the same module as the callback functions (init, locked and open). This is normally good programming practice, to have the code corresponding to one process contained in one module.

The third argument, Code, is a term which is passed as-is to the callback function init. Here, init gets the correct code for the lock as indata.

The fourth argument, [], is a list of options. See gen_fsm(3) for available options.

If name registration succeeds, the new gen_fsm process calls the callback function code_lock:init(Code). This function is expected to return {ok, StateName, StateData}, where StateName is the name of the initial state of the gen_fsm. In this case locked, assuming the door is locked to begin with. StateData is the internal state of the gen_fsm. (For gen_fsms, the internal state is often referred to 'state data' to distinguish it from the state as in states of a state machine.) In this case, the state data is the button sequence so far (empty to begin with) and the correct code of the lock.

init(Code) ->
    {ok, locked, {[], Code}}.

Note that gen_fsm:start_link is synchronous. It does not return until the gen_fsm has been initialized and is ready to receive notifications.

gen_fsm:start_link must be used if the gen_fsm is part of a supervision tree, i.e. is started by a supervisor. There is another function gen_fsm:start to start a stand-alone gen_fsm, i.e. a gen_fsm which is not part of a supervision tree.

3.4 Notifying About Events

The function notifying the code lock about a button event is implemented using gen_fsm:send_event/2:

button(Digit) ->
    gen_fsm:send_event(code_lock, {button, Digit}).

code_lock is the name of the gen_fsm and must agree with the name used to start it. {button, Digit} is the actual event.

The event is made into a message and sent to the gen_fsm. When the event is received, the gen_fsm calls StateName(Event, StateData) which is expected to return a tuple {next_state, StateName1, StateData1}. StateName is the name of the current state and StateName1 is the name of the next state to go to. StateData1 is a new value for the state data of the gen_fsm.

locked({button, Digit}, {SoFar, Code}) ->
    case [Digit|SoFar] of
        Code ->
            do_unlock(),
            {next_state, open, {[], Code}, 30000};
        Incomplete when length(Incomplete)<length(Code) ->
            {next_state, locked, {Incomplete, Code}};
        _Wrong ->
            {next_state, locked, {[], Code}};
    end.

open(timeout, State) ->
    do_lock(),
    {next_state, locked, State}.

If the door is locked and a button is pressed, the complete button sequence so far is compared with the correct code for the lock and, depending on the result, the door is either unlocked and the gen_fsm goes to state open, or the door remains in state locked.

3.5 Timeouts

When a correct code has been givened, the door is unlocked and the following tuple is returned from locked/2:

{next_state, open, {[], Code}, 30000};

30000 is a timeout value in milliseconds. After 30000 ms, i.e. 30 seconds, a timeout occurs. Then StateName(timeout, StateData) is called. In this case, the timeout occurs when the door has been in state open for 30 seconds. After that the door is locked again:

open(timeout, State) ->
    do_lock(),
    {next_state, locked, State}.

3.6 All State Events

Sometimes an event can arrive at any state of the gen_fsm. Instead of sending the message with gen_fsm:send_event/2 and writing one clause handling the event for each state function, the message can be sent with gen_fsm:send_all_state_event/2 and handled with Module:handle_event/3:

-module(code_lock).
...
-export([stop/0]).
...

stop() ->
    gen_fsm:send_all_state_event(code_lock, stop).

...

handle_event(stop, _StateName, StateData) ->
    {stop, normal, StateData}.

3.7 Stopping

3.7.1 In a Supervision Tree

If the gen_fsm is part of a supervision tree, no stop function is needed. The gen_fsm will automatically be terminated by its supervisor. Exactly how this is done is defined by a shutdown strategy set in the supervisor.

If it is necessary to clean up before termination, the shutdown strategy must be a timeout value and the gen_fsm must be set to trap exit signals in the init function. When ordered to shutdown, the gen_fsm will then call the callback function terminate(shutdown, StateName, StateData):

init(Args) ->
    ...,
    process_flag(trap_exit, true),
    ...,
    {ok, StateName, StateData}.

...

terminate(shutdown, StateName, StateData) ->
    ..code for cleaning up here..
    ok.

3.7.2 Stand-Alone Gen_Fsms

If the gen_fsm is not part of a supervision tree, a stop function may be useful, for example:

...
-export([stop/0]).
...

stop() ->
    gen_fsm:send_all_state_event(code_lock, stop).
...

handle_event(stop, _StateName, StateData) ->
    {stop, normal, StateData}.

...

terminate(normal, _StateName, _StateData) ->
    ok.

The callback function handling the stop event returns a tuple {stop,normal,StateData1}, where normal specifies that it is a normal termination and StateData1 is a new value for the state data of the gen_fsm. This will cause the gen_fsm to call terminate(normal,StateName,StateData1) and then terminate gracefully:

3.8 Handling Other Messages

If the gen_fsm should be able to receive other messages than events, the callback function handle_info(Info, StateName, StateData) must be implemented to handle them. Examples of other messages are exit messages, if the gen_fsm is linked to other processes (than the supervisor) and trapping exit signals.

handle_info({'EXIT', Pid, Reason}, StateName, StateData) ->
    ..code to handle exits here..
    {next_state, StateName1, StateData1}.

ejabberd模块开发

2008-03-31T22:04:00.001-07:00

Introduction

ejabberd internal modules works as plugins. Each module is an erlang module with a name beginning with “mod_”. If you don’t already know Erlang, you should also take a look at this doc.

API of the module

All the internal modules must use the “gen_mod” behavior.

It must provide the following API:

start(Host, Opts) -> ok stop(Host) -> ok * Host = string() * Opts = [{Name, Value}] * Name = Value = string()

Host is the name of the virtual host running the module. The start/2 and stop/1 functions are called for each virtual host at start and stop time of the server.
Opts is a lists of options set in the configuration file for the module. They can be retrieved with the gen mod:get opt/3 function.

解决Qt4.4 beta输入法侯选框的问题

2008-03-31T22:03:00.005-07:00

昨天在QInputContext.cpp找了半天，尝试修改代码也没有解决侯选框出不来的问题。在说到解决方法之前，首先感谢souce insight，没有这么好的编辑器，我都不知道要怎么去看这些大型工程的源代码。

查看了一下IME编辑相关的资料，顺代的在qt4.4的源码中搜索与WM_IME开头的消息除理代码，不多，也就几条，最后在qapplication_win.cpp让我给发现了，嘿嘿，就是在处理WM_IME_NOTIFY消息的代码有问题，代码如下：

case WM_IME_NOTIFY:
            // special handling for ime, only for widgets in a popup
            if (wParam == IMN_OPENCANDIDATE) {
                imeParentWnd = hwnd;
                if (QApplication::activePopupWidget()) {
                    // temporarily disable the mouse grab to allow mouse input in
                    // the ime candidate window. The actual handle is untouched
                    if (autoCaptureWnd)
                        ReleaseCapture();
                }
            } else if (wParam == IMN_CLOSECANDIDATE) {
                imeParentWnd = 0;
                if (QApplication::activePopupWidget()) {
                    // undo the action above, when candidate window is closed
                    if (autoCaptureWnd)
                        SetCapture(autoCaptureWnd);
                }
            }

result = false;//added by zhongfanglin@gmail.com
            break;
        default:
            result = false;                        // event was not processed
            break;
        }
    }

    if (evt_type != QEvent::None) {                // simple event
        QEvent e(evt_type);
        result = qt_sendSpontaneousEvent(widget, &e);
    }

//add by zhongfanglin@anzsoft.com
    if(AnzSkin->winEventFilter(&msg,&res))
        RETURN(res);
    //end add

if (result)
RETURN(false);

do_default:
RETURN(QWinInputContext::DefWindowProc(hwnd,message,wParam,lParam))
}

作用没太看明白，但是从代码可以看出，WM_IME_NOTIFY被拦截了，并没有交给默认的消息处理函数，所以在case WM_IME_NOTIFY:节添加了一句代码，result = false,重新编译QtGui模块，运行程序，期待已久的输入法侯选框终于出现了。

不过没明白的是，我用的五笔加加在修改这个代码之前是能出侯选框的，看来是五笔加加不是用的IME体系的侯选框处理机制。

顺便发个牢骚，现在好用的拼音输入法真多，又漂亮又好用，为吓咪就没人做好看漂亮又好用的五笔呢。。。。。。只怪用不来拼音输入法，只好老实的用偶的五笔了。

升级至Qt4.4又碰到输入法问题

2008-03-31T22:03:00.003-07:00

昨天把QT库的版本升级到了4.4_beta以解决之前版本的切换窗口之后输入法叫不起来的问题。我自己用的是五笔加加输入法，因为测试过没有问题，所以决定不等Qt发布Release版本，先用beta版本对付一下。

升级的时候也碰到不少问题，特别是stylesheet的问题，很多style都要修改，郁闷。最后还是完成了升级。

不过晚上的时候老詹说又有输入法问题，输入法的选字窗口显示了。咦，我的五笔加加工作是正常的啊。我是那种典型的发音不准的南方人，所以从来不用拼音输入法的，一直都用五笔加加输入法，所以没有发现这个问题！装上其它的输入法试了一下，果然是！！！郁闷

在网上搜索了一下，发现在有个在Trolltech工作的中国工程师齐亮，给他发了封邮件询问一下这个问题，不知道会不会看到这个邮件。希望这个问题能够解决。

Qt4.4 QTabWidget fixed

2008-03-31T22:03:00.001-07:00

在设置tabPosition为west，并且想设置tab只显示Icon不显示文字时Tab会比想要的效果长，为了解决这个问题，修改

QStyleSheetStyle::sizeFromContents函数，修改部分如下：（只要修改一句代码，注释一些代码即可）

#ifndef QT_NO_TABBAR
    case CT_TabBarTab: {
        QRenderRule subRule = renderRule(w, opt, PseudoElement_TabBarTab);
        sz = csz.expandedTo(subRule.minimumContentsSize());
        if (subRule.hasBox() || subRule.hasBorder()) {
            sz = subRule.boxSize(sz);
            int spaceForIcon = 0;
            bool vertical = false;
            if (const QStyleOptionTab *tab = qstyleoption_cast<const QStyleOptionTab *>(opt)) {
                if (!tab->icon.isNull())
                    spaceForIcon = 6 /* icon offset */ + 4 /* spacing */ + 2 /* magic */; // ###: hardcoded to match with common style
                vertical = verticalTabs(tab->shape);
            }
            return sz;//commited by zhongfanglin@gmail.com + QSize(vertical ? 0 : spaceForIcon, vertical ? spaceForIcon : 0);
        }
        break;
                       }
#endif // QT_NO_TABBAR

firefox开发：使用XPCOM访问Windows注册表（Accessing the Windows Registry Using XPCOM）

2008-03-31T22:02:00.003-07:00

Introduction

When implementing Windows-specific functionality, it is often useful to access the Windows registry for information about the environment or other installed programs. To this end, there exist XPCOM interfaces to read and write registry data. This article will show you how to use the available interfaces in several Mozilla products.

The examples in this document are all written in JavaScript using XPCOM.

[edit] Support in Firefox 1.5 or newer

In Firefox 1.5, a new API was added, nsIWindowsRegKey, which provides extensive registry functionality. The interface follows the Windows API fairly closely, but with many of the low-level details taken care of for you. If you are writing an extension that only needs to support Firefox 1.5 or newer, then you only need to read this section.

[edit] A simple example

Here's a simple example showing how to read your Windows ProductId:

var wrk = Components.classes["@mozilla.org/windows-registry-key;1"]
                    .createInstance(Components.interfaces.nsIWindowsRegKey);
wrk.open(wrk.ROOT_KEY_LOCAL_MACHINE,
         "SOFTWARE\\Microsoft\\Windows\\CurrentVersion",
         wrk.ACCESS_READ);
var id = wrk.readStringValue("ProductId");
wrk.close();

This example, while simple, shows several important things about using the interface. First, you must use createInstance() to get an object implementing this interface, not getService(). Second, you must call open() on the key before attempting to read a value.

Notice in the open() call that the root key to use is specified using the named constants available on the nsIWindowsRegKey interface, in this case ROOT_KEY_LOCAL_MACHINE, which corresponds to HKEY_LOCAL_MACHINE in the Windows registry. Also notice that the path to the key has backslashes escaped, a necessity in JavaScript and C++ string constants.

The desired access rights are specified using a named constant from the interface, in this example ACCESS_READ. This can be very important when dealing with non-Administrator accounts with restricted privileges.

The value is read using readStringValue(). You have to specify what type of data you expect to read, which we will expand on later. Finally, note that you should close the key when you are done to avoid wasting system resources.

[edit] Opening Registry Keys

Before doing anything with a registry key you must first open the key you are interested in. The example above demonstates this using the open() method. If you want to create a new key, you can use the create() method, which takes the same parameters as open(). Note that it is not an error to call create() on an existing key, and doing so has the same result as calling open().

Both of these methods take a root key as the first parameter. From JavaScript, you will want to use the named constants on the interface for this parameter. They are:

ROOT_KEY_CLASSES_ROOT — Corresponds to HKEY_CLASSES_ROOT

ROOT_KEY_CURRENT_USER — Corresponds to HKEY_CURRENT_USER

ROOT_KEY_LOCAL_MACHINE — Corresponds to HKEY_LOCAL_MACHINE

The second parameter for open() and create() is the path to the key. As noted in the example above, you will need to escape backslashes within the string.

The third parameter for open() and create() is the access mode. It is specified as a bitwise combination of flags defined on the interface. You can read the interface documentation for a full explanation, but we will show only the three most commonly used modes here:

ACCESS_READ — For reading values, enumerating keys, and receiving notifications

ACCESS_WRITE — For setting values and creating sub keys

ACCESS_ALL — Access for all operations

In addition to open() and create(), there are the openChild() and createChild() methods. You can call these methods on an already-opened registry key to open a child key. Both methods take a relative path and access mode as parameters and return a new object implementing nsIWindowsRegKey. Here's the simple example again, but using openChild():

var wrk = Components.classes["@mozilla.org/windows-registry-key;1"]
                    .createInstance(Components.interfaces.nsIWindowsRegKey);
wrk.open(wrk.ROOT_KEY_LOCAL_MACHINE,
         "SOFTWARE\\Microsoft",
         wrk.ACCESS_READ);
var subkey = wrk.openChild("Windows\\CurrentVersion", wrk.ACCESS_READ);
var id = subkey.readStringValue("ProductId");
subkey.close();
wrk.close();

Once you've opened a registry key, you can begin to make use of it.

[edit] Reading Registry Values

Probably the most common action associated with the Windows registry is reading values. The simple example above shows how to read an existing string value. However, Windows registry values can have several data types, so you need to ensure that you read the correct type. You can check the type of a value using the method getValueType(). This method returns an integer indicating the data type of the value. The data types supported by this interface are defined as named constants on the interface as follows:

TYPE_NONE — Probably not useful

TYPE_STRING — A Unicode string value

TYPE_BINARY — Binary data

TYPE_INT — A 32 bit integer

TYPE_INT64 — A 64 bit integer

Each of these types (except TYPE_NONE) has a corresponding method to read the value data:

readStringValue()

readBinaryValue()

readIntValue()

readInt64Value()

Since JavaScript is a dynamically-typed language, you may wish to use the following code to handle all types of data. In this function, wrk is expected to be an already opened nsIWindowsRegKey.

function readRegistryValue(wrk, value)
{
  switch (wrk.getValueType(value)) {
    case wrk.TYPE_STRING:
      return wrk.readStringValue(value);
    case wrk.TYPE_BINARY:
      return wrk.readBinaryValue(value);
    case wrk.TYPE_INT:
      return wrk.readIntValue(value);
    case wrk.TYPE_INT64:
      return wrk.readInt64Value(value);
  }
  // unknown type
  return null;
}

[edit] Writing Registry Values

Writing registry values is quite similar to reading. For each supported data type, there is a write*Value() method complementary to the read*Value() method. Don't forget that if you are writing a new value, you may need to create() the parent key first. This example demonstrates writing a new string value:

var wrk = Components.classes["@mozilla.org/windows-registry-key;1"]
                    .createInstance(Components.interfaces.nsIWindowsRegKey);
wrk.create(wrk.ROOT_KEY_CURRENT_USER,
           "SOFTWARE\\MDC\\Test",
           wrk.ACCESS_WRITE);
wrk.writeStringValue("TestValue", "Hello World!");
wrk.close();

[edit] Checking the Existence of Keys and Values

Before you attempt to read a value or open a child key, you should check to see whether it exists first. The nsIWindowsRegKey interface provides methods for both of these—hasValue() and hasChild()—as demonstrated in this example:

var wrk = Components.classes["@mozilla.org/windows-registry-key;1"]
                    .createInstance(Components.interfaces.nsIWindowsRegKey);
wrk.open(wrk.ROOT_KEY_LOCAL_MACHINE,
           "SOFTWARE\\Microsoft",
           wrk.ACCESS_READ);
if (wrk.hasChild("Windows")) {
  var subkey = wrk.openChild("Windows\\CurrentVersion", wrk.ACCESS_READ);
  var id;
  if (subkey.hasValue("ProductId"))
    id = subkey.readStringValue("ProductId");
  subkey.close();
}
wrk.close();

[edit] Enumerating Registry Keys and Values

In some situations, you may want to enumerate a number of keys or values whose names you do not know. The nsIWindowsRegKey interface provides the childCount, getChildName(), valueCount, and getValueName() properties and methods for enumerating keys and values respectively. You can use these methods to read a list of values or recursively access a branch of the registry. This example reads all the startup programs in one key of the registry.

var wrk = Components.classes["@mozilla.org/windows-registry-key;1"]
                    .createInstance(Components.interfaces.nsIWindowsRegKey);
wrk.open(wrk.ROOT_KEY_LOCAL_MACHINE,
         "SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Run",
         wrk.ACCESS_READ);
for (var i=0; i<wrk.valueCount; i++) {
  var name  = wrk.getValueName(i);
  var value = readRegistryValue(wrk, name);
  // do something interesting here...
}
wrk.close();

For simplicity, this example assumes the existence of the readRegistryValue() function defined above.

[edit] Removing Registry Keys and Values

To remove child keys and values from the registry, you can use the removeChild() and removeValue() methods. removeChild() removes a child key and all of its values, but will fail if the key has any child keys of its own. In that case you must manually enumerate the children and remove them individually. This example shows how to recursively delete a registry key and all of its children. Use with caution!

function removeChildrenRecursive(wrk)
{
  // we count backwards because we're removing them as we go
  for (var i = wrk.childCount - 1; i >= 0; i--) {
    var name   = wrk.getChildName(i);
    var subkey = wrk.openChild(name, wrk.ACCESS_ALL);
    removeChildrenRecursive(subkey);
    subkey.close();
    wrk.removeChild(name);
  }
}

var wrk = Components.classes["@mozilla.org/windows-registry-key;1"]
                    .createInstance(Components.interfaces.nsIWindowsRegKey);
wrk.open(wrk.ROOT_KEY_CURRENT_USER,
         "SOFTWARE\\MDC\\Test",
         wrk.ACCESS_ALL);
removeChildrenRecursive(wrk);
wrk.close();

[edit] Monitoring Registry Keys

If you would like to know whether a registry key has changed since you last checked it, you can use the startWatching(), stopWatching(), and hasChanged() methods. You must call startWatching() for the key to be monitored. The method takes one parameter, a boolean indicating whether child keys should be watched. After that, you can call hasChanged() to determine whether or not you need to reread the value. Calling hasChanged() automatically resets the watch, so you can be sure that if it returns true there are changes. This example demonstrates a trivial registry value cache for one key:

var cache = {};

function readRegistryValueNoCache(wrk, value)
{
  switch (wrk.getValueType(value)) {
    case wrk.TYPE_STRING:
      return wrk.readStringValue(value);
    case wrk.TYPE_BINARY:
      return wrk.readBinaryValue(value);
    case wrk.TYPE_INT:
      return wrk.readIntValue(value);
    case wrk.TYPE_INT64:
      return wrk.readInt64Value(value);
  }
  // unknown type
  return null;
}

function readRegistryValue(wrk, value)
{
  if (wrk.hasChanged()) {
    // wipe out the cache
    cache = {};
  }

  if (value in cache) {
    return cache[value];
  }
  
  cache[value] = readRegistryValueNoCache(wrk, value);
  return cache[value];
}

var wrk = Components.classes["@mozilla.org/windows-registry-key;1"]
                    .createInstance(Components.interfaces.nsIWindowsRegKey);
wrk.open(wrk.ROOT_KEY_LOCAL_MACHINE,
         "SOFTWARE\\Microsoft\\Windows\\CurrentVersion",
         wrk.ACCESS_READ);
wrk.startWatching(false); // only watch the values on this key, not child keys
var id = readRegistryValue(wrk, "ProductId");
/* later you can read this again,
   and it should come from the cache unless
   there have been changes to the registry.
   Remember to call wrk.close() when you
   are finished!
*/

[edit] Support in Firefox 1.0

Firefox 1.0 includes a much simpler interface to the Windows registry, without most of the functionality supported in newer versions. The functionality is exposed in the nsIWindowsShellService interface. It consists of only one method, getRegistryEntry(), and a set of named constants to specify the root key. You can use it as shown in the following example:

var wss = Components.classes["@mozilla.org/browser/shell-service;1"]
                    .getService(Components.interfaces.nsIWindowsShellService);
var id = wss.getRegistryEntry(wss.HKLM,
                              "SOFTWARE\\Microsoft\\Windows\\CurrentVersion",
                              "ProductId");

Note: There's no way to set a registry value using this interface.

[edit] Support in SeaMonkey and Other Non-toolkit Applications

In older versions of SeaMonkey and other non-toolkit-based applications, an interface existed called nsIWindowsRegistry, containing the same method and named constants as the methods described above for Firefox 1.0. It can be used as follows:

var wss = Components.classes["@mozilla.org/winhooks;1"]
                    .getService(Components.interfaces.nsIWindowsRegistry);
var id = wss.getRegistryEntry(wss.HKLM,
                              "SOFTWARE\\Microsoft\\Windows\\CurrentVersion",
                              "ProductId");

[edit] Backwards Compatibility

If you need to support Firefox 1.0 and other older browser versions, you should check to see which interfaces are available. The following skeleton code will allow you to determine which interface to use:

if ("@mozilla.org/windows-registry-key;1" in Components.classes) {
  // Firefox 1.5 or newer
}
else if ("@mozilla.org/winhooks;1" in Components.classes) {
  // SeaMonkey or other older non-toolkit application
}
else if ("@mozilla.org/browser/shell-service;1" in Components.classes) {
  var wss = Components.classes["@mozilla.org/browser/shell-service;1"]
                      .getService(Components.interfaces.nsIWindowsShellService);
  if ("getRegistryEntry" in wss) {
    // Firefox 1.0
  }
  else {
    // nothing supported
  }
}
else {
  // nothing supported
}

[转]在Windows中查看端口占用情况的简单方法

2008-03-31T22:02:00.001-07:00

用这个命令，在DOS窗口执行：netstat -ano
看看占用0.0.0:80端口的PID是多少
然后在“任务管理器”中查到与该PID对应的程序。
如果任务管理器的进程页中看不到PID栏，则在任务管理器的菜单〖查看〗〖选择列〗中选择一下

XUL Tutorial:XUL Structure

2008-03-31T22:01:00.003-07:00

XUL,是XML User Interface Language的缩写。

XUL Tutorial:XUL Structure

From MDC

« Previous Next »

[hide]

We'll begin by looking at how the XUL is handled in Mozilla.

[edit] How XUL is Handled

In Mozilla, XUL is handled much in the same way that HTML or other types of content are handled. When you type the URL of an HTML page into the browser's address field, the browser locates the web site and downloads the content. The Mozilla rendering engine takes the content in the form of HTML source and transforms it into a document tree. The tree is then converted into a set of objects that can be displayed on the screen. Style sheets (CSS), images, and other technologies are used to control the presentation. XUL functions in much the same way.

In fact, in Mozilla, all document types, whether they are HTML or XUL, or even SVG, are all handled by the same underlying code. This means that the same CSS properties may be used to style both HTML and XUL, and many of the features can be shared between both. However, there are some features that are specific to HTML such as forms, and others which are specific to XUL such as overlays. Since XUL and HTML are handled in the same way, you can load both from either your local file system, from a web page, or from an extension or standalone XULRunner application.

Content from remote sources eg http://localhost/~username/, regardless of whether they are HTML or XUL or another document type, are limited in the type of operations they can perform, for security reasons. For this reason, Mozilla provides a method of installing content locally and registering the installed files as part of its chrome system. This allows a special URL form to be used called a chrome:// URL. By accessing a file using a chrome URL, the files receive elevated privileges to access local files, access preferences and bookmarks and perform other privileged operations. Obviously, web pages do not get these privileges, unless they are signed with a digital certificate and the user has granted permission to perform these operations.

This chrome package registration is the way Firefox extensions are able to add features to the browser. The extensions are small packages of XUL files, JavaScript, style sheets and images packed together into a single file. This file can be created by using a ZIP utility. When the user downloads it, it will be installed onto the user's machine. It will hook into the browser using a XUL specific feature called an overlay which allows the XUL from the extension and the XUL in the browser to combine together. To the user, it may seem like the extension has modified the browser, but in reality, the code is all separate, and the extension may be uninstalled easily. Registered packages are not required to use overlays, of course. If they don't, you won't be able to access them via the main browser interface, but you can still access them via the chrome URL, if you know what it is.

Standalone XUL applications may include XUL code in a similar way, but, of course, the XUL for the application will be included as part of the installation, instead of having to be installed separately as an extension. However, this XUL code will be registered in the chrome system such that the application can display the UI.

It is worth noting that the Mozilla browser itself is actually just a set of packages containing XUL files, JavaScript and style sheets. These files are accessed via a chrome URL and have enhanced privileges and work just like any other package. Of course, the browser is much larger and more sophisticated than most extensions. Firefox and Thunderbird as well as number of other components are all written in XUL and are all accessible via chrome URLs. You can examine these packages by looking in the chrome directory where Firefox or another XUL application is installed.

The chrome URL always begins with 'chrome://'. Much like how the 'http://' URL always refers to remote web sites accessed using HTTP and the 'file://' URL always refers to local files, the 'chrome://' URL always refers to installed packages and extensions. We'll look more at the syntax of a chrome URL in the next section. It is important to note that when accessing content through a chrome URL, it gains the enhanced privileges described above that other kinds of URLs do not. For instance, an HTTP URL does not have any special privileges, and an error will occur if a web page tries, for example, to read a local file. However, a file loaded via a chrome URL will be able to read files without restriction.

This distinction is important. This means that there are certain things that content of web pages cannot do, such as read the user's bookmarks. This distinction is not based on the kind of content being displayed; only on the type of URL used. Both HTML and XUL placed on a web site have no extra permissions; however both HTML and XUL loaded through a chrome URL have enhanced permissions.

If you are going to use XUL on a web site, you can just put the XUL file on the web site as you would an HTML file, and then load its URL in a browser http://localhost/xul.php. Ensure that your web server is configured to send XUL files with the content type of application/vnd.mozilla.xul+xml (eg with PHP header('Content-type: application/vnd.mozilla.xul+xml');). This content type is how Mozilla knows the difference between HTML and XUL. Mozilla does not use the file extension, unless reading files from the file system, but you should use the .xul extension for all XUL files. You can load XUL files from your own machine by opening them in the browser, or by double-clicking the file in your file manager.

Remember that remote XUL will have significant restrictions on what it can do.

[edit] Document types: HTML XML XUL CSS

Mozilla uses a distinctly different kind of document object (DOM) for HTML and XUL, although they share most of their functionality. There are three main types of document in Mozilla: HTML, XML, and XUL. Naturally, the HTML document is used for HTML documents, the XUL document is used for XUL documents, and the XML document is used for other types of XML documents. Since XUL is also XML, the XUL document is a subtype of the more generic XML document. There are subtle differences in functionality. For example, while the form controls on an HTML page are accessible via the document.forms property, this property isn't available for XUL documents, since XUL doesn't have forms in the HTML sense. Likewise, XUL specific features such as overlays and templates are only available in XUL documents.

This distinction between documents is important. It is possible to use many XUL features in HTML or XML documents since they aren't document type specific; however other features require the right kind of document. For instance, you can use the XUL layout types in other documents since they don't rely on the XUL document type to function.

To summarize the points made above:

Mozilla renders both HTML and XUL using the same underlying engine and uses CSS to specify their presentation.
XUL may be loaded from a remote site, the local file system, or installed as a package and accessed using a chrome URL. This last option is what browser extensions do.
Chrome URLs may be used to access installed packages and open them with enhanced privileges.
HTML, XML, and XUL each have a different document type. Some features may be used in any document type whereas some features are specific to one kind of document.

The next few sections describe the basic structure of a chrome package which can be installed into Mozilla. However, if you just want to get started building a simple application, you may skip ahead to Creating a Window and save this section for later.

[edit] Package Organization

Mozilla is organized in such a way that you can have as many components as you want pre-installed. Each extension is also a component with a separate chrome URL. It also has one component for each installed theme and locale. Each of these components, or packages, is made up of a set of files that describe the user interface for it. For example, the messenger component has descriptions of the mail messages list window, the composition window and the address book dialogs.

The packages that are provided with Mozilla are located within the chrome directory, which are in the directory where you installed Mozilla. The chrome directory is where you find all the files that describe the user interface used by the Mozilla browser, mail client, and other applications. Typically, you put all the XUL files for an application in this directory, although extensions are installed in the extensions directory for a particular user. Just copying a XUL file into the chrome directory doesn't give the file any extra permissions, nor can it be accessed via a chrome URL. To gain the extra privileges, you will need to create a manifest file and put that in the chrome directory. This file is easy to create, as it is typically only a couple of lines long. It is used to map a chrome URL to a file or directory path on the disk where the XUL files are located. Details of how to create this file will be discussed in a later section.

The only way to create content that can be accessed through a chrome URL is by creating a package as described in the next few sections. This directory is called 'chrome' likely because it seemed like a convenient name to use for the directory where the chrome packages that are included with Mozilla are kept.

To further the confusion, there are two other places where the word "chrome" might appear. These are the -chrome command line argument and the chrome modifier to the window.open() function. Neither of these features grant extra privileges; instead they are used to open a new top-level window without the browser UI such as the menu and toolbar. You will commonly use this feature in more complex XUL applications since you wouldn't want the browser UI to exist around your dialog boxes.

The files for a package are usually combined into a single JAR file. A JAR file may created and examined using a ZIP utility. For instance, you can open the JAR files in Mozilla's chrome directory to see the basic structure of a package. Although it's normal to combine the files into a JAR file, packages may also be accessed in expanded form into a directory. Although you don't normally distribute a package this way, it is handy during development since you can edit the file directly and then reload the XUL file without having to repackage or reinstall the files.

By default, Mozilla applications parse XUL files and scripts, and store a pre-compiled version in memory for the remainder of the application session. This improves performance. However, because of this, the XUL will be not be reloaded even when the source files are changed. To disable this mechanism, it is necessary to change the preference nglayout.debug.disable_xul_cache. In Firefox, this preference may be added to the user preferences by typing "about:config" in the address field, and setting this value to true. Or, just manually edit your user.js preferences file and add the following line:

pref("nglayout.debug.disable_xul_cache", true);

There are usually three different parts to a chrome package, although they are all optional. Each part is stored in a different directory. These three sets are the content, the skin, and the locale, which are all described below. A particular package might provide one or more skins and locales, but a user can replace them with their own. In addition, the package might include several different applications, each accessible via different chrome URLs. The packaging system is flexible enough so that you can include whatever parts you need and allow other parts, such as the text for different languages, to be downloaded separately.

The three types of chrome packages are:

Content - Windows and scripts

The declarations of the windows and the user interface elements contained within them. These are stored in XUL files, which have a .xul extension. A content package can have multiple XUL files, but the main window should have a filename that is the same as the package name. For example, the editor package will have a file within it called editor.xul. Scripts are placed in separate files alongside the XUL files.

Skin - Style sheets, images and other theme specific files

Style sheets describe details of the appearance of a window. They are stored separately from XUL files to facilitate modifying the skin (theme) of an application. Any images used are stored here also.

Locale - Locale specific files

All the text that is displayed within a window is stored separately. This way, a user can have a set for their own language.

[edit] Content Packages

The name of the JAR file might describe what it contains, but you can't be sure unless you view its contents. Let's use the browser package included with Firefox as an example. If you extract the files in browser.jar, you will find that it contains a directory structure much like the following:

content
   browser
      browser.xul
      browser.js
      -- other browser XUL and JS files goes here --
      bookmarks
         -- bookmarks files go here --
      preferences
         -- preferences files go here --
.
.
.

This is easily recognizable as a content package, as the top-level directory is called content. For skins, this directory will usually be called skin and for locales, it will usually be called locale. This naming scheme isn't necessary, but this is a common convention to make the parts of a package clearer. Some packages may include a content section, a skin, and a locale. In this case, you will find a subdirectory for each type. For example, Chatzilla is distributed in this way.

The content/browser directory contains a number of files with .xul and .js extensions. The XUL files are the ones with the .xul extension. The files with .js extensions are JavaScript files containing scripts that handle the functionality of a window. Many XUL files have a script file associated with them, and some may have more than one.

In the listing above, two files have been shown. There are of course others, but for simplicity they aren't shown. The file browser.xul is the XUL file that describes the main browser window. The main window for a content package should have the same name as the package with a .xul extension. In this case, the package name is "browser" so we expect to find browser.xul. Some of the other XUL files describe separate windows. For example, the file pageInfo.xul describes the page info dialog.

Many packages will include a contents.rdf file, which describes the package, its author, and the overlays it uses. However, this file is obsolete and has been replaced with a simpler mechanism. This newer method is the manifest file mentioned earlier, and you will find these as files with the .manifest extension in the chrome directory. For instance, browser.manifest describes the browser package.

Several subdirectories, such as bookmarks and preferences, describe additional sections of the browser component. They are placed in different directories only to keep the files more organized.

[edit] Skins or Themes

Although the underlying code for Mozilla calls them skins and the user interface calls them themes, they're both referring to the same thing. The classic.jar file describes the default theme provided with Firefox. The structure is similar to the content packages. For example, examining classic.jar:

skin
   classic
      browser
         browser.css
         -- other browser skin files go here --
      global
         -- global skin files go here --
.
.
.

Again, this directory structure isn't necessary and is used for convenience. You can actually put all the files in one directory at the top level and not use subdirectories. However, for larger applications, subdirectories are used to separate the different components. In the example above, a directory exists for theme related files for the browser and another for global theme related files. The global directory contains skin files that are general to all packages. These files will apply to all components and will be included with your own standalone applications. The global part defines the appearance of all of the common XUL widgets, whereas the other directories have files that are specific to those applications. Firefox includes both the global and browser theme files in one archive, but they can be included separately.

A skin is made up of CSS files and a number of images used to define the look of an interface. The file browser.css is used by browser.xul and contains styles that define the appearance of various parts of the browser interface. Again, note how the file browser.css has the same name as the package. By changing the CSS files, you can adjust the appearance of a window without changing its function. This is how you can create a new theme. The XUL part remains the same but the skin part changes independently.

[edit] Locales

The file en-US.jar describes the language information for each component, in this case for US English. Like the skins, each language file contains files that specify text used by the package for a specific language. The locale structure is similar to the others, so it won't be listed here.

The localized text is stored in two types of files: DTD files and properties files. The DTD files have a .dtd extension and contain entity declarations, one for each text string that is used in a window. For example, the file browser.dtd contains entity declarations for each menu command. In addition, keyboard shortcuts for each command are also defined, because they may be different for each language. DTD files are used by XUL files so, in general, you will have one per XUL file. The locale part also contains properties files, which are similar, but are used by script files. The file browser.properties contains a few such localized strings.

This structure allows you to translate Mozilla or a component into a different language by just adding a new locale for that language. You don't have to change the XUL code at all. In addition, another person could supply a separate package that applies a skin or locale to your content part, thus providing support for a new theme or language without having to change the original package.

[edit] Other Packages

There is a special package called toolkit (or global). We saw the global directory earlier for skins. The file toolkit.jar contains the corresponding content part for it. It contains some global dialogs and definitions. It also defines the default appearance and functionality of the various common XUL widgets such as textboxes and buttons. The files located in the global part of a skin package contain the default look for all of the XUL interface elements. The toolkit package is used by all XUL applications.

[edit] Adding a Package

Mozilla places the packages that are included with the installation in the chrome directory. However, they do not need to be placed there. When installing another package, you can place it anywhere on the disk, as long as a manifest file points to it. It is common to place packages into the chrome directory simply because it is convenient; however, they will work just as well from another directory or somewhere on your local network. You cannot store them on a remote site, unless the remote site is mounted through the local file system.

There are two chrome directories used for XUL applications: one is installed in the same place where the application is installed, while the other is part of user's profile. The former allows packages that are shared by all users while the latter allows packages to be created only for a specific user or users. Extensions, while installed in a separate extensions directory, are also usually user specific. Any manifest files located in either chrome directory will be examined to see which packages are installed.

In the next section, we'll look at how to refer to chrome packages using the chrome URL.

Setting up extension development environment

2008-03-31T22:01:00.001-07:00

Setting up extension development environment

From MDC

This article gives suggestions on how to set up your Mozilla application for extension development.

[hide]

[edit] Development preferences

These preferences will make debugging easier at the expense of lower performance.

See Editing Configuration Files for information on setting preferences. Note that some of these preferences are not listed in about:config by default, so you'll need to create new (boolean) entries for them.

See below under "Development Profile" to setup a separate development profile before you make these changes.

javascript.options.showInConsole = true. Logs errors in chrome files to the Error Console.
nglayout.debug.disable_xul_cache = true. Disables the XUL cache so that changes to windows and dialogs do not require a restart. This assumes you're using directories rather than JARs. Changes to XUL overlays will still require reloading of the document overlaid.
browser.dom.window.dump.enabled = true. Enables the use of the dump() statement to print to the standard console. See window.dump for more info. You can also use nsIConsoleService from privileged script.
javascript.options.strict = true. Enables strict JavaScript warnings in the Error Console. Note that since many people have this setting turned off when developing, you will see lots of warnings for problems with their code in addition to warnings for your own extension. You can filter those with Console².

[edit] Development extensions

These extensions may help you with your development.

DOM Inspector, an option of a custom installation.
Venkman, a JavaScript Debugger.
Extension Developer's Extension
Console²
Chrome List
Firebug
Execute JS
XPCOMViewer, an XPCOM inspector

[edit] Development profile

To avoid the performance hit of development-related prefs and extensions, and to avoid borking your personal data, you can use a separate profile for development work.

You can run two instances of Firefox using separate profiles if you start Firefox with the -no-remote parameter. For example, the following command will run your development profile whether "normal" Firefox is already running or not. (Assuming your development profile is called "dev"):

start "" "%ProgramFiles%\Mozilla Firefox\firefox.exe" -no-remote -P dev

To run Firefox with default profile just run "firefox" or "firefox -P default", as usual.

[edit] Custom code location

Rather than having to constantly reinstall the extension whenever you change something and to protect your source files from accidental deletion when uninstalling, you can place your source outside your profile in a location of your choosing.

Find the extension ID from the install.rdf included with your extension

Create a file in your_profile_directory/extensions/ with the above ID as the filename (eg. `your_profile_directory/extensions/{46D1B3C0-DB7A-4b1a-863A-6EE6F77ECB58}`) (Find your profile directory)

The contents of this file should be the path to the folder that contains your install.rdf file. (eg. `/full/path/to/yourExtension`. Windows users should use the drive name (CAPS) and backslashes instead of slashes: eg. `C:\full\path\to\yourExtension`). In Firefox 3, if you already the extension installed via XPI, you might need to install one or all of the extensions.* files in the profile folder. Backup first, but these files will be regenerated.

Place the file in the extensions folder of your profile and restart the application.

[edit] Using directories rather than JARs

Regardless of whether you choose to package your extension's chrome in a JAR or in directories, developing in directories is simpler. If you choose a JARed structure for releasing, you can still develop with a directory structure by editing your chrome.manifest. For example, rather than having

content	myExtension	jar:chrome/myExtension.jar!/content/

use

content	myExtension	chrome/content/

QT程序的Jpeg图像不能显示的问题

2007-05-21T20:54:00.000-07:00

QT编译的程序在本机编译后到目标机器不能显示Jpeg图像，需要把QT目录下的plugins/imageformats目录下的jpeg1.dll等图片格式支持文件一起发布到目标应用程序的目录的imageformats目录下