aboutsummaryrefslogtreecommitdiffstats
path: root/lib/ose/src/ose.erl
diff options
context:
space:
mode:
Diffstat (limited to 'lib/ose/src/ose.erl')
-rw-r--r--lib/ose/src/ose.erl452
1 files changed, 452 insertions, 0 deletions
diff --git a/lib/ose/src/ose.erl b/lib/ose/src/ose.erl
new file mode 100644
index 0000000000..ff7147233f
--- /dev/null
+++ b/lib/ose/src/ose.erl
@@ -0,0 +1,452 @@
+%%
+%% %CopyrightBegin%
+%%
+%% Copyright Ericsson AB 2013. All Rights Reserved.
+%%
+%% The contents of this file are subject to the Erlang Public License,
+%% Version 1.1, (the "License"); you may not use this file except in
+%% compliance with the License. You should have received a copy of the
+%% Erlang Public License along with this software. If not, it can be
+%% retrieved online at http://www.erlang.org/.
+%%
+%% Software distributed under the License is distributed on an "AS IS"
+%% basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+%% the License for the specific language governing rights and limitations
+%% under the License.
+%%
+%% %CopyrightEnd%
+%%
+%% @doc Interface module for OSE messaging and process monitoring from Erlang
+%%
+%% For each mailbox created through {@link open/1} a OSE phantom process with
+%% that name is started. Since phantom processes are used the memory footprint
+%% of each mailbox is quite small.
+%%
+%% To receive messages you first have to subscribe to the specific message
+%% numbers that you are interested in with {@link listen/2}. The messages
+%% will be sent to the Erlang process that created the mailbox.
+%%
+%% @end
+%%
+-module(ose).
+
+%%==============================================================================
+%% Exported API
+%%==============================================================================
+-export([open/1,
+ close/1,
+ get_id/1,
+ get_name/2,
+ hunt/2,
+ dehunt/2,
+ attach/2,
+ detach/2,
+ send/4,
+ send/5,
+ listen/2
+ ]).
+
+%%==============================================================================
+%% Types
+%%==============================================================================
+-opaque mailbox() :: port().
+%% Mailbox handle. Implemented as an erlang port.
+
+-opaque mailbox_id() :: integer().
+%% Mailbox ID, this is the same as the process id of an OSE process.
+%% An integer.
+
+-type message_number() :: 0..4294967295.
+%% OSE Signal number
+
+-opaque hunt_ref() :: {mailbox(),integer()}.
+%% Reference from a hunt request. This term will be included
+%% in a successful hunt response.
+
+-opaque attach_ref() :: {mailbox(),integer()}.
+%% Reference from an attach request. This term will be included
+%% in the term returned when the attached mailbox disappears.
+
+-export_type([mailbox_id/0,
+ message_number/0,
+ mailbox/0,
+ hunt_ref/0,
+ attach_ref/0]).
+
+%%==============================================================================
+%% Defines
+%%==============================================================================
+-define(DRIVER_NAME, "ose_signal_drv").
+-define(GET_SPID, 1).
+-define(GET_NAME, 2).
+-define(HUNT, 100).
+-define(DEHUNT, 101).
+-define(ATTACH, 102).
+-define(DETACH, 103).
+-define(SEND, 104).
+-define(SEND_W_S, 105).
+-define(LISTEN, 106).
+-define(OPEN, 200).
+
+-define(INT_32BIT(Int),(is_integer(Int) andalso (Int >= 0) andalso (Int < (1 bsl 32)))).
+
+%%==============================================================================
+%% API functions
+%%==============================================================================
+
+%%------------------------------------------------------------------------------
+%% @doc Create a mailbox with the given name and return a port that handles
+%% the mailbox.
+%%
+%% An OSE phantom process with the given name will be created that will send any
+%% messages sent through this mailbox. Any messages sent to the new OSE process
+%% will automatically be converted to an Erlang message and sent to the Erlang
+%% process that calls this function. See {@link listen/2} for details about the
+%% format of the message sent.
+%%
+%% The caller gets linked to the created mailbox.
+%%
+%% raises: `badarg' | `system_limit'
+%%
+%% @see liten/2
+%% @end
+%%------------------------------------------------------------------------------
+-spec open(Name) -> Port when
+ Name :: iodata(),
+ Port :: mailbox().
+open(Name) ->
+ try open_port({spawn_driver,?DRIVER_NAME}, [binary]) of
+ Port ->
+ try port_command(Port,[?OPEN,Name]) of
+ true ->
+ receive
+ {ose_drv_reply,Port,{error,Error}} ->
+ close(Port),
+ erlang:error(Error,[Name]);
+ {ose_drv_reply,Port,ok} ->
+ Port
+ end
+ catch
+ error:badarg -> close(Port),erlang:error(badarg,[Name])
+ end
+ catch
+ error:badarg -> erlang:error(badarg,[Name])
+ end.
+
+%%------------------------------------------------------------------------------
+%% @doc Close a mailbox
+%%
+%% This kills the OSE phantom process associated with this mailbox.
+%%
+%% Will also consume any ``{'EXIT',Port,_}'' message from the port that comes
+%% due to the port closing when the calling process traps exits.
+%%
+%% raises: `badarg'
+%% @end
+%%------------------------------------------------------------------------------
+-spec close(Port) -> ok when
+ Port :: mailbox().
+close(Port) when is_port(Port) ->
+ %% Copied from prim_inet
+ case erlang:process_info(self(), trap_exit) of
+ {trap_exit,true} ->
+ link(Port),
+ catch erlang:port_close(Port),
+ receive {'EXIT',Port,_} -> ok end;
+ {trap_exit,false} ->
+ catch erlang:port_close(Port),
+ ok
+ end;
+close(NotPort) ->
+ erlang:error(badarg,[NotPort]).
+
+%%------------------------------------------------------------------------------
+%% @doc Get the mailbox id for the given port.
+%%
+%% The mailbox id is the same as the OSE process id of the OSE phantom process
+%% that this mailbox represents.
+%%
+%% raises: `badarg'
+%% @end
+%%------------------------------------------------------------------------------
+-spec get_id(Port) -> Pid when
+ Port :: mailbox(),
+ Pid :: mailbox_id().
+get_id(Port) ->
+ try port_control(Port, ?GET_SPID, <<>>) of
+ <<Spid:32>> -> Spid
+ catch error:_Error ->
+ erlang:error(badarg,[Port])
+ end.
+
+%%------------------------------------------------------------------------------
+%% @doc Get the mailbox name for the given mailbox id.
+%%
+%% The mailbox name is the name of the OSE process with process id Pid.
+%%
+%% This call will fail with badarg if the underlying system does not support
+%% getting the name from a process id.
+%%
+%% raises: `badarg'
+%% @end
+%%------------------------------------------------------------------------------
+-spec get_name(Port, Pid) -> Name | undefined when
+ Port :: mailbox(),
+ Pid :: mailbox_id(),
+ Name :: binary().
+get_name(Port, Pid) when ?INT_32BIT(Pid) ->
+ try port_control(Port, ?GET_NAME, <<Pid:32>>) of
+ [] -> undefined;
+ Res -> Res
+ catch error:_Error ->
+ erlang:error(badarg,[Port,Pid])
+ end;
+get_name(Port, Pid) ->
+ erlang:error(badarg,[Port,Pid]).
+
+
+%%------------------------------------------------------------------------------
+%% @doc Hunt for OSE process by name.
+%%
+%% Will send `{mailbox_up, Port, Ref, MboxId}'
+%% to the calling process when the OSE process becomes available.
+%%
+%% Returns a reference term that can be used to cancel the hunt
+%% using {@link dehunt/2}.
+%%
+%% raises: `badarg'
+%%
+%% @end
+%%------------------------------------------------------------------------------
+-spec hunt(Port, HuntPath) -> Ref when
+ Port :: mailbox(),
+ HuntPath :: iodata(),
+ Ref :: hunt_ref().
+hunt(Port, HuntPath) ->
+ try port_command(Port, [?HUNT,HuntPath]) of
+ true ->
+ receive
+ {ose_drv_reply,Port,{error,Error}} ->
+ erlang:error(Error,[Port,HuntPath]);
+ {ose_drv_reply,Port,Ref} ->
+ Ref
+ end
+ catch error:_Error ->
+ erlang:error(badarg,[Port,HuntPath])
+ end.
+
+%%------------------------------------------------------------------------------
+%% @doc Stop hunting for OSE process.
+%%
+%% If a message for this hunt has been sent but not received
+%% by the calling process, it is removed from the message queue.
+%% Note that this only works if the same process that did
+%% the hunt does the dehunt.
+%%
+%% raises: `badarg'
+%%
+%% @see hunt/2
+%% @end
+%%------------------------------------------------------------------------------
+-spec dehunt(Port, Ref) -> ok when
+ Port :: mailbox(),
+ Ref :: hunt_ref().
+dehunt(Port, {Port,Ref}) when ?INT_32BIT(Ref) ->
+ try port_command(Port, <<?DEHUNT:8, Ref:32>>) of
+ true ->
+ receive
+ {ose_drv_reply,Port,{error,enoent}} ->
+ %% enoent could mean that it is in the message queue
+ receive
+ {mailbox_up, Port, {Port,Ref}, _} ->
+ ok
+ after 0 ->
+ ok
+ end;
+ {ose_drv_reply,Port,ok} ->
+ ok
+ end
+ catch error:_Error ->
+ erlang:error(badarg,[Port,{Port,Ref}])
+ end;
+dehunt(Port,Ref) ->
+ erlang:error(badarg,[Port,Ref]).
+
+%%------------------------------------------------------------------------------
+%% @doc Attach to an OSE process.
+%%
+%% Will send `{mailbox_down, Port, Ref, MboxId}'
+%% to the calling process if the OSE process exits.
+%%
+%% Returns a reference that can be used to cancel the attachment
+%% using {@link detach/2}.
+%%
+%% raises: `badarg' | `enomem'
+%%
+%% @end
+%%------------------------------------------------------------------------------
+-spec attach(Port,Pid) -> Ref when
+ Port :: mailbox(),
+ Pid :: mailbox_id(),
+ Ref :: attach_ref().
+attach(Port, Spid) when ?INT_32BIT(Spid) ->
+ try port_command(Port, <<?ATTACH:8, Spid:32>>) of
+ true ->
+ receive
+ {ose_drv_reply,Port,{error,Error}} ->
+ erlang:error(Error,[Port,Spid]);
+ {ose_drv_reply,Port,Ref} ->
+ Ref
+ end
+ catch error:_Error ->
+ erlang:error(badarg,[Port,Spid])
+ end;
+attach(Port,Spid) ->
+ erlang:error(badarg,[Port,Spid]).
+
+
+%%------------------------------------------------------------------------------
+%% @doc Remove attachment to an OSE process.
+%%
+%% If a message for this monitor has been sent but not received
+%% by the calling process, it is removed from the message queue.
+%% Note that this only works of the same process
+%% that did the attach does the detach.
+%%
+%% raises: `badarg'
+%%
+%% @see attach/2
+%% @end
+%%------------------------------------------------------------------------------
+-spec detach(Port,Ref) -> ok when
+ Port :: mailbox(),
+ Ref :: attach_ref().
+detach(Port, {Port,Ref} ) when ?INT_32BIT(Ref) ->
+ try port_command(Port, <<?DETACH:8, Ref:32>>) of
+ true ->
+ receive
+ {ose_drv_reply,Port,{error,enoent}} ->
+ %% enoent could mean that it is in the message queue
+ receive
+ {mailbox_down,Port,{Port,Ref},_} ->
+ ok
+ after 0 ->
+ ok
+ end;
+ {ose_drv_reply,Port,ok} ->
+ ok
+ end
+ catch error:_Error ->
+ erlang:error(badarg,[Port,{Port,Ref}])
+ end;
+detach(Port,Ref) ->
+ erlang:error(badarg,[Port,Ref]).
+
+%%------------------------------------------------------------------------------
+%% @doc Send an OSE message.
+%%
+%% The message is sent from the OSE process' own ID that is: `get_id(Port)'.
+%%
+%% raises: `badarg'
+%%
+%% @see send/5
+%% @end
+%%------------------------------------------------------------------------------
+-spec send(Port,Pid,SigNo,SigData) -> ok when
+ Port :: mailbox(),
+ Pid :: mailbox_id(),
+ SigNo :: message_number(),
+ SigData :: iodata().
+send(Port, Spid, SigNo, SigData) when ?INT_32BIT(Spid), ?INT_32BIT(SigNo) ->
+ try erlang:port_command(Port, [<<?SEND:8, Spid:32, SigNo:32>>, SigData]) of
+ true -> ok
+ catch error:_Error ->
+ erlang:error(badarg,[Port,Spid,SigNo,SigData])
+ end;
+send(Port,Spid,SigNo,SigData) ->
+ erlang:error(badarg,[Port,Spid,SigNo,SigData]).
+
+
+%%------------------------------------------------------------------------------
+%% @doc Send an OSE message with different sender.
+%%
+%% As {@link send/4} but the sender will be `SenderPid'.
+%%
+%% raises: `badarg'
+%%
+%% @see send/4
+%% @end
+%%------------------------------------------------------------------------------
+-spec send(Port,Pid,SenderPid,SigNo,SigData) -> ok when
+ Port :: mailbox(),
+ Pid :: mailbox_id(),
+ SenderPid :: mailbox_id(),
+ SigNo :: message_number(),
+ SigData :: iodata().
+send(Port, Spid, SenderPid, SigNo, SigData)
+ when ?INT_32BIT(Spid), ?INT_32BIT(SenderPid), ?INT_32BIT(SigNo) ->
+ try erlang:port_command(Port, [<<?SEND_W_S:8, Spid:32, SenderPid:32,
+ SigNo:32>>, SigData]) of
+ true -> ok
+ catch error:_Error ->
+ erlang:error(badarg,[Port,Spid,SenderPid,SigNo,SigData])
+ end;
+send(Port,Spid,SenderPid,SigNo,SigData) ->
+ erlang:error(badarg,[Port,Spid,SenderPid,SigNo,SigData]).
+
+%%------------------------------------------------------------------------------
+%% @doc Start listening for specified OSE signal numbers.
+%%
+%% The mailbox will send `{message,Port,{FromMboxId,ToMboxId,MsgNo,MsgData}}'
+%% to the process that created the mailbox when an OSE message with any
+%% of the specified `SigNos' arrives.
+%%
+%% Repeated calls to listen will replace the current set of signal numbers to
+%% listen to. i.e
+%%
+%% ```1>ose:listen(MsgB,[1234,12345]).
+%% ok
+%% 2> ose:listen(MsgB,[1234,123456]).
+%% ok.'''
+%%
+%% The above will first listen for signals with numbers 1234 and 12345, and then
+%% replace that with only listening to 1234 and 123456.
+%%
+%% With the current implementation it is not possible to listen to all signal
+%% numbers.
+%%
+%% raises: `badarg' | `enomem'
+%%
+%% @end
+%%------------------------------------------------------------------------------
+-spec listen(Port, SigNos) -> ok when
+ Port :: mailbox(),
+ SigNos :: list(message_number()).
+listen(Port, SigNos) when is_list(SigNos) ->
+ USSigNos = lists:usort(SigNos),
+ BinSigNos = try
+ << <<SigNo:32>> ||
+ SigNo <- USSigNos,
+ ?INT_32BIT(SigNo) orelse erlang:error(badarg)
+ >>
+ catch _:_ ->
+ erlang:error(badarg,[Port,SigNos])
+ end,
+ try port_command(Port, [?LISTEN, BinSigNos]) of
+ true ->
+ receive
+ {ose_drv_reply,Port,{error,Error}} ->
+ erlang:error(Error,[Port,SigNos]);
+ {ose_drv_reply,Port,Else} ->
+ Else
+ end
+ catch error:_Error ->
+ erlang:error(badarg,[Port,SigNos])
+ end;
+listen(Port, SigNos) ->
+ erlang:error(badarg,[Port,SigNos]).
+
+
+%%%=============================================================================
+%%% Internal functions
+%%%=============================================================================