November 21th Saturday

最新推荐文章于 2024-03-19 07:16:32 发布

Lu_ming

最新推荐文章于 2024-03-19 07:16:32 发布

阅读量1.4k

点赞数

文章标签： erlang output command descriptor struct byte

本文链接：https://blog.csdn.net/Lu_ming/article/details/4837626

版权

How the Erlang communicate with an exteranl program?

Erlang runtime system and communicate with this process through a byte-oriented communication channel. The Erlang side of the communication is controlled by an Erlang port. The process that creates a port is called the connected process for that port. The connected process has a special signiﬁcance: all messages to the external program must be tagged with the PID of the connected process, and all messages from the external program are sent to the connected processes.

As far as the programmer is concerned, the port behaves just like an Erlang process. You can send messages to it, you can register it (just like a process), and so on. If the external program crashes, then an exit signal will be sent to the connected process, and if the connected process dies, then the external program will be killed.

Many programming languages allow code in foreign languages to be linked into the application executable. In Erlang, we don’t allow this for reasons of safety. If we were to link an external program into the Erlang executable, then a mistake in the external program could easily crash the Erlang system. For this reason, all foreign language code must be run outside the Erlang system in an external operating system process. The Erlang system and the external process communicate through a byte stream.

There an example that is the communication between the C progam and the erlang.

.c files

/* example1.c */

int twice(int x) {
return 2 * x;
}

int sum(int x, int y) {
return x + y;
}

/* erl_comm.c */

#include <unistd.h>

typedef unsigned char byte;

int read_cmd(byte *buf);
int write_cmd(byte *buf, int len);
int read_exact(byte *buf, int len);
int write_exact(byte *buf, int len);

int read_cmd(byte *buf)
{
int len;

if (read_exact(buf, 2) != 2)
return (-1);
len = (buf[0] << 8) | buf[1];
return read_exact(buf, len);
}

int write_cmd(byte *buf, int len)
{
byte li;

li = (len >> 8) & 0xff;
write_exact(&li, 1);

li = len & 0xff;
write_exact(&li, 1);

return write_exact(buf, len);
}

int read_exact(byte *buf, int len)
{
int i, got = 0;

do {
    if ((i = read(0, buf + got, len - got)) <= 0)
      return i;
    got += i;
} while(got < len);

return len;
}

int write_exact(byte *buf, int len)
{
int i, wrote = 0;

do {
if ((i = write(1, buf + wrote, len - wrote)) <= 0)
return i;

wrote += i;
} while(wrote < len);

return len;
}

/* example1_driver.c */

#include <stdio.h>

typedef unsigned char byte;

int read_cmd(byte *buff);
int write_cmd(byte *buffer, int len);

int main() {
int fn, arg1, arg2, result;
byte buff[100];

while (read_cmd(buff) > 0) {
    fn = buff[0];
    if (fn == 1) {
      arg1 = buff[1];
      result = twice(arg1);
    } else if (fn == 2) {
      arg1 = buff[1];
      arg2 = buff[2];
      result = sum(arg1, arg2);
    }

buff[0] = result;
write_cmd(buff, 1);
}

return 0;
}

To make a C program, use it.

gcc -o example1 example1.c erl_comm.c example1_driver.c

.erl file

%%% example1.erl

-module(example1).
-export([start/0, stop/0]).
-export([twice/1, sum/2]).

start() ->
spawn(fun() ->
  register(example1, self()),
  process_flag(trap_exit, true),
  Port = open_port({spawn, "./example1"}, [{packet, 2}]),
  loop(Port)
end).

stop() ->
example1 ! stop.

twice(X) -> call_port({twice, X}).
sum(X, Y) -> call_port({sum, X, Y}).

call_port(Msg) ->
example1 ! {call, self(), Msg},
receive
{example1, Result} ->
Result
end.

loop(Port) ->
receive
  {call, Caller, Msg} ->
   Port ! {self(), {command, encode(Msg)}},
   receive
     {Port, {data, Data}} ->
       Caller ! {example1, decode(Data)}
   end,
   loop(Port);
  stop ->
   Port ! {self(), close},
   receive
     {Port, closed} ->
       exit(normal)
   end;
  {'EXIT', Port, Reason} ->
   exit({port_terminated, Reason})
end.

encode({twice, X}) -> [1, X];
encode({sum, X, Y}) -> [2, X, Y].

decode([Int]) -> Int.

To make a .beam file, use it. And run it in the Erlang shell.

erlc -W

Running the example

1> example1:start().
<0.32.0>
2> example1:sum(45, 32).
77
4> example1:twice(10).
20

...

Another way to link into an external program

In this case, the program is written as a shared library that is dynamically linked into the Erlang runtime system. The
linked-in driver appears to the programmer as a port program and obeys exactly the same protocol as for a port program.

Creating a linked-in driver is the most efﬁcient way of interfacing foreign-language code with Erlang, but it is also the

most dangerous. Any fatal error in the linked-in driver will crash the Erlang system and affect all processes in the system. For this reason, using linked-in drivers is not recommended; they should be used only when all else fails.

There is an example.

.erl file

%%% example1_lid.erl

-module(example1_lid).
-export([start/0, stop/0]).
-export([twice/1, sum/2]).

start() ->
start("example1_drv").

start(SharedLib) ->
    case erl_ddll:load_driver(".", SharedLib) of
ok -> ok;
{error, already_loaded} -> ok;
_ -> exit({error, could_not_load_driver})
    end,
    spawn(fun() -> init(SharedLib) end).

init(SharedLib) ->
    register(example1_lid, self()),
    Port = open_port({spawn, SharedLib}, []),
    loop(Port).

stop() ->
example1_lid ! stop.

twice(X) -> call_port({twice, X}).
sum(X,Y) -> call_port({sum, X, Y}).

call_port(Msg) ->
    example1_lid ! {call, self(), Msg},
    receive
{example1_lid, Result} ->
     Result
    end.

loop(Port) ->
    receive
{call, Caller, Msg} ->
     Port ! {self(), {command, encode(Msg)}},
     receive
  {Port, {data, Data}} ->
      Caller ! {example1_lid, decode(Data)}
     end,
     loop(Port);
stop ->
     Port ! {self(), close},
     receive
  {Port, closed} ->
      exit(normal)
     end;
{'EXIT', Port, Reason} ->
     io:format("~p ~n", [Reason]),
     exit(port_terminated)
    end.

encode({twice, X}) -> [1, X];
encode({sum, X, Y}) -> [2, X, Y].

decode([Int]) -> Int.

.c files

/* erl_driver.h */

/* ``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 via the world wide web 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.
*
* The Initial Developer of the Original Code is Ericsson Utvecklings AB.
* Portions created by Ericsson are Copyright 1999, Ericsson Utvecklings
* AB. All Rights Reserved.''
*
* $Id$
*/

/*
* Include file for erlang driver writers.
*/

#ifndef __ERL_DRIVER_H__
#define __ERL_DRIVER_H__

#ifdef HAVE_CONFIG_H
# include "config.h"
#endif

#include <stdlib.h>

#if defined(VXWORKS)
# include <ioLib.h>
typedef struct iovec SysIOVec;
#elif defined(__WIN32__) || defined(_WIN32) || defined(_WIN32_)
#ifndef STATIC_ERLANG_DRIVER
   /* Windows dynamic drivers, everything is different... */
#define ERL_DRIVER_TYPES_ONLY
#define WIN32_DYNAMIC_ERL_DRIVER
#endif
/*
* This structure can be cast to a WSABUF structure.
*/
typedef struct _SysIOVec {
    unsigned long iov_len;
    char* iov_base;
} SysIOVec;
#else /* Unix */
# ifdef HAVE_SYS_UIO_H
#    include <sys/types.h>
#    include <sys/uio.h>
typedef struct iovec SysIOVec;
# else
typedef struct {
    char* iov_base;
    size_t iov_len;
} SysIOVec;
# endif
#endif

#ifndef EXTERN
# ifdef __cplusplus
# define EXTERN extern "C"
# else
# define EXTERN extern
# endif
#endif

/* Values for mode arg to driver_select() */

#define DO_READ (1 << 0)
#define DO_WRITE (1 << 1)
#ifdef _OSE_
#define DO_START (1 << 2)
#define DO_STOP (1 << 3)
#endif /* _OSE_ */

/* Values for set_port_control_flags() */

#define PORT_CONTROL_FLAG_BINARY (1 << 0)
#define PORT_CONTROL_FLAG_HEAVY (1 << 1)

/* Values for get_port_flags() */

#define PORT_FLAG_BINARY (1 << 0)
#define PORT_FLAG_LINE (1 << 1)

/*
* A binary as seen in a driver. Note that a binary should never be
* altered by the driver when it has been sent to Erlang.
*/

typedef struct erl_drv_binary {
long orig_size; /* total length of binary */
char orig_bytes[1]; /* the data (char instead of byte!) */
} ErlDrvBinary;

/*
* Note: These types are incomplete to catch type errors easier.
*/

typedef struct _erl_drv_data* ErlDrvData; /* Data to be used by the driver itself. */
#ifndef ERL_SYS_DRV
typedef struct _erl_drv_event* ErlDrvEvent; /* An event to be selected on. */
typedef struct _erl_drv_port* ErlDrvPort; /* A port descriptor. */
#endif
typedef struct _erl_drv_port* ErlDrvThreadData; /* Thread data. */

#if !defined(__WIN32__) && !defined(_WIN32) && !defined(_WIN32_) && !defined(USE_SELECT)
struct erl_drv_event_data {
short events;
short revents;
};
#endif
typedef struct erl_drv_event_data *ErlDrvEventData; /* Event data */

/*
* Error codes that can be return from driver.
*/

/*
* Exception code from open_port/2 will be {'EXIT',{einval,Where}}.
*/
#define ERL_DRV_ERROR_GENERAL ((ErlDrvData) -1)

/*
* Exception code from open_port/2 will be {'EXIT',{Errno,Where}},
* where Errno is a textual representation of the errno variable
* (e.g. eacces if errno is EACCES).
*/
#define ERL_DRV_ERROR_ERRNO ((ErlDrvData) -2)

/*
* Exception code from open_port/2 will be {'EXIT',{badarg,Where}}.
*/
#define ERL_DRV_ERROR_BADARG ((ErlDrvData) -3)

typedef struct erl_io_vec {
    int vsize;   /* length of vectors */
    int size;   /* total size in bytes */
    SysIOVec* iov;
    ErlDrvBinary** binv;
} ErlIOVec;

/*
* This structure defines a driver.
*/

typedef struct erl_drv_entry {
    int (*init)(void);  /* called at system start up for statically
       linked drivers, and after loading for
       dynamically loaded drivers */

#ifndef ERL_SYS_DRV
    ErlDrvData (*start)(ErlDrvPort port, char *command);
    /* called when open_port/2 is invoked.
       return value -1 means failure. */
#else
    ErlDrvData (*start)(ErlDrvPort port, char *command, SysDriverOpts* opts);
    /* special options, only for system driver */
#endif
    void (*stop)(ErlDrvData drv_data);
                                /* called when port is closed, and when the
       emulator is halted. */
    void (*output)(ErlDrvData drv_data, char *buf, int len);
    /* called when we have output from erlang to
       the port */
    void (*ready_input)(ErlDrvData drv_data, ErlDrvEvent event);
    /* called when we have input from one of
       the driver's handles) */
    void (*ready_output)(ErlDrvData drv_data, ErlDrvEvent event);
    /* called when output is possible to one of
       the driver's handles */
    char *driver_name;  /* name supplied as command
       in open_port XXX ? */
    void (*finish)(void);        /* called before unloading the driver -
       DYNAMIC DRIVERS ONLY */
    void *handle;  /* not used -- here for backwards compatibility */
    int (*control)(ErlDrvData drv_data, unsigned int command, char *buf,
     int len, char **rbuf, int rlen);
    /* "ioctl" for drivers - invoked by
       port_command/3) */
    void (*timeout)(ErlDrvData drv_data); /* Handling of timeout in driver */
    void (*outputv)(ErlDrvData drv_data, ErlIOVec *ev);
    /* called when we have output from erlang
       to the port */
    void (*ready_async)(ErlDrvData drv_data, ErlDrvThreadData thread_data);
    void (*flush)(ErlDrvData drv_data);
                                /* called when the port is about to be
       closed, and there is data in the
       driver queue that needs to be flushed
       before 'stop' can be called */
    int (*call)(ErlDrvData drv_data, unsigned int command, char *buf,
     int len, char **rbuf, int rlen, unsigned int *flags);
                                /* Works mostly like 'control', a syncronous
       call into the driver. */
    void (*event)(ErlDrvData drv_data, ErlDrvEvent event,
    ErlDrvEventData event_data);
                                /* Called when an event selected by
       driver_event() has occurred */
} ErlDrvEntry;

/*
* This macro is used to name a dynamic driver's init function in
* a way that doesn't lead to conflicts. This is crucial when using
* operating systems that has one namespace for all symbols
* (e.g. VxWorks). Example: if you have an dynamic driver C source
* file named echo_drv.c, you use the macro like this:
*
*    DRIVER_INIT(echo_drv)
*    {
* ....
*    }
*
* This function well be called by the Erlang I/O system when the driver is loaded.
* It must initialize a ErlDrvEntry structure and return a pointer to it.
*/

/* For windows dynamic drivers */
#ifndef ERL_DRIVER_TYPES_ONLY

#if defined(VXWORKS)
# define DRIVER_INIT(DRIVER_NAME) ErlDrvEntry* DRIVER_NAME ## _init(void)
#elif defined(__WIN32__)
# define DRIVER_INIT(DRIVER_NAME) __declspec(dllexport) ErlDrvEntry* driver_init(void)
#else
# define DRIVER_INIT(DRIVER_NAME) ErlDrvEntry* driver_init(void)
#endif

/*
* These are the functions available for driver writers.
*/
EXTERN int driver_select(ErlDrvPort port, ErlDrvEvent event, int mode, int on);
EXTERN int driver_event(ErlDrvPort port, ErlDrvEvent event,
   ErlDrvEventData event_data);
EXTERN int driver_output(ErlDrvPort port, char *buf, int len);
EXTERN int driver_output2(ErlDrvPort port, char *hbuf, int hlen,
     char *buf, int len);
EXTERN int driver_output_binary(ErlDrvPort port, char *hbuf, int hlen,
    ErlDrvBinary* bin, int offset, int len);
EXTERN int driver_outputv(ErlDrvPort port, char* hbuf, int hlen, ErlIOVec *ev,
     int skip);
EXTERN int driver_vec_to_buf(ErlIOVec *ev, char *buf, int len);
EXTERN int driver_set_timer(ErlDrvPort port, unsigned long time);
EXTERN int driver_cancel_timer(ErlDrvPort port);
EXTERN int driver_read_timer(ErlDrvPort port, unsigned long *time_left);

/*
* Get plain-text error message from within a driver
*/
EXTERN char* erl_errno_id(int error);

/*
* The following functions are used to initiate a close of a port
* from a driver.
*/
EXTERN int driver_failure_eof(ErlDrvPort port);
EXTERN int driver_failure_atom(ErlDrvPort port, char *string);
EXTERN int driver_failure_posix(ErlDrvPort port, int error);
EXTERN int driver_failure(ErlDrvPort port, int error);
EXTERN int driver_exit (ErlDrvPort port, int err);

/*
* Port attributes
*/
EXTERN void set_busy_port(ErlDrvPort port, int on);
EXTERN void set_port_control_flags(ErlDrvPort port, int flags);

EXTERN int get_port_flags(ErlDrvPort port);

/* Binary interface */

/*
* NOTE: DO NOT overwrite a binary with new data (if the data is delivered);
* since the binary is a shared object it MUST be written once.
*/

EXTERN ErlDrvBinary* driver_alloc_binary(int size);
EXTERN ErlDrvBinary* driver_realloc_binary(ErlDrvBinary *bin, int size);
EXTERN void driver_free_binary(ErlDrvBinary *bin);

/* Referenc count on driver binaries */
EXTERN long driver_binary_get_refc(ErlDrvBinary *dbp);
EXTERN long driver_binary_inc_refc(ErlDrvBinary *dbp);
EXTERN long driver_binary_dec_refc(ErlDrvBinary *dbp);

/* Allocation interface */
EXTERN void *driver_alloc(size_t size);
EXTERN void *driver_realloc(void *ptr, size_t size);
EXTERN void driver_free(void *ptr);

/* Queue interface */
EXTERN int driver_enq(ErlDrvPort port, char* buf, int len);
EXTERN int driver_pushq(ErlDrvPort port, char* buf, int len);
EXTERN int driver_deq(ErlDrvPort port, int size);
EXTERN int driver_sizeq(ErlDrvPort port);
EXTERN int driver_enq_bin(ErlDrvPort port, ErlDrvBinary *bin, int offset,
int len);
EXTERN int driver_pushq_bin(ErlDrvPort port, ErlDrvBinary *bin, int offset,
int len);

EXTERN int driver_peekqv(ErlDrvPort port, ErlIOVec *ev);
EXTERN SysIOVec* driver_peekq(ErlDrvPort port, int *vlen);
EXTERN int driver_enqv(ErlDrvPort port, ErlIOVec *ev, int skip);
EXTERN int driver_pushqv(ErlDrvPort port, ErlIOVec *ev, int skip);

/*
* Add and remove driver entries.
*/
EXTERN void add_driver_entry(ErlDrvEntry *de);
EXTERN int remove_driver_entry(ErlDrvEntry *de);

/*
* Misc.
*/
EXTERN int null_func(void);

#endif /* !ERL_DRIVER_TYPES_ONLY */

/* Constants for return flags from the 'port_call' callback */
#define DRIVER_CALL_KEEP_BUFFER 0x1

/* ErlDrvTerm is the type to use for casts when building
* terms that should be sent to connected process,
* for instance a tuple on the form {tcp, Port, [Tag|Binary]}
*
* ErlDrvTerm spec[] = {
*    ERL_DRV_ATOM, driver_mk_atom("tcp"),
*    ERL_DRV_PORT, driver_mk_port(drv->ix),
*             ERL_DRV_INT, REPLY_TAG,
*             ERL_DRV_BINARY, (ErlDrvTerm)bin, 50, 0,
*             ERL_DRV_LIST, 2,
*    ERL_DRV_TUPLE, 3,
* }
*
*/

typedef unsigned long ErlDrvTermData;

#define TERM_DATA(x) ((ErlDrvTermData) (x))

/* Possible types to send from driver          Argument type */
#define ERL_DRV_NIL         ((ErlDrvTermData) 1) /* None */
#define ERL_DRV_ATOM        ((ErlDrvTermData) 2) /* driver_mk_atom(string) */
#define ERL_DRV_INT         ((ErlDrvTermData) 3) /* int */
#define ERL_DRV_PORT        ((ErlDrvTermData) 4) /* driver_mk_port(ix) */
#define ERL_DRV_BINARY      ((ErlDrvTermData) 5) /* ErlDriverBinary*,
         * int size, int offs */
#define ERL_DRV_STRING      ((ErlDrvTermData) 6) /* char*, int */
#define ERL_DRV_TUPLE       ((ErlDrvTermData) 7) /* int */
#define ERL_DRV_LIST        ((ErlDrvTermData) 8) /* int */
#define ERL_DRV_STRING_CONS ((ErlDrvTermData) 9) /* char*, int */
#define ERL_DRV_PID         ((ErlDrvTermData) 10) /* driver_connected,... */

#define ERL_DRV_FLOAT ((ErlDrvTermData) 11) /* double * */

#ifndef ERL_DRIVER_TYPES_ONLY

/* make terms for driver_output_term and driver_send_term */
EXTERN ErlDrvTermData driver_mk_atom(char*);
EXTERN ErlDrvTermData driver_mk_port(ErlDrvPort);
EXTERN ErlDrvTermData driver_connected(ErlDrvPort);
EXTERN ErlDrvTermData driver_caller(ErlDrvPort);
extern const ErlDrvTermData driver_term_nil;
EXTERN ErlDrvTermData driver_mk_term_nil(void);
EXTERN ErlDrvPort driver_create_port(ErlDrvEntry* driver,
         ErlDrvTermData connected, /* pid */
         char* name, /* driver name */
         ErlDrvData drv_data);

/* output term data to the port owner */
EXTERN int driver_output_term(ErlDrvPort ix, ErlDrvTermData* data, int len);
/* output term data to a specific process */
EXTERN int driver_send_term(ErlDrvPort ix, ErlDrvTermData to,
ErlDrvTermData* data, int len);

/* Async IO functions */
EXTERN long driver_async(ErlDrvPort ix,
    unsigned int* key,
    void (*async_invoke)(void*),
    void* async_data,
    void (*async_free)(void*));

EXTERN int driver_async_cancel(unsigned int key);

EXTERN int driver_attach(ErlDrvPort ix);
EXTERN int driver_detach(ErlDrvPort ix);

/* These were removed from the ANSI version, now they're back. */

EXTERN void *driver_dl_open(char *);
EXTERN void *driver_dl_sym(void *, char *);
EXTERN int driver_dl_close(void *);
EXTERN char *driver_dl_error(void);

#endif /* !ERL_DRIVER_TYPES_ONLY */

#ifdef WIN32_DYNAMIC_ERL_DRIVER
# include "erl_win_dyn_driver.h"
#endif

#endif

/* example1_lid.c */

#include <stdio.h>
#include "erl_driver.h"

typedef struct {
ErlDrvPort port;
} example_data;

static ErlDrvData example_drv_start(ErlDrvPort port, char *buff)
{
    example_data* d = (example_data*)driver_alloc(sizeof(example_data));
    d->port = port;
    return (ErlDrvData)d;
}

static void example_drv_stop(ErlDrvData handle)
{
driver_free((char*)handle);
}

static void example_drv_output(ErlDrvData handle, char *buff, int bufflen)
{
    example_data* d = (example_data*)handle;
    char fn = buff[0], arg = buff[1], res;
    if (fn == 1) {
      res = twice(arg);
    } else if (fn == 2) {
      res = sum(buff[1], buff[2]);
    }
    driver_output(d->port, &res, 1);
}

ErlDrvEntry example_driver_entry = {
    NULL,               /* F_PTR init, N/A */
    example_drv_start, /* L_PTR start, called when port is opened */
    example_drv_stop,   /* F_PTR stop, called when port is closed */
    example_drv_output, /* F_PTR output, called when erlang has sent
      data to the port */
    NULL,               /* F_PTR ready_input,
                           called when input descriptor ready to read*/
    NULL,               /* F_PTR ready_output,
                           called when output descriptor ready to write */
    "example1_drv",     /* char *driver_name, the argument to open_port */
    NULL,               /* F_PTR finish, called when unloaded */
    NULL,               /* F_PTR control, port_command callback */
    NULL,               /* F_PTR timeout, reserved */
    NULL                /* F_PTR outputv, reserved */
};

DRIVER_INIT(example_drv) /* must match name in driver_entry */
{
return &example_driver_entry;
}

To make a .so file, use it.

gcc -o example1_drv.so -fpic -shared example1.c example1_lid.c

running it.

1> c(example1_lid).
{ok,example1_lid}
2> example1_lid:start().
<0.41.0>
3> example1_lid:twice(50).
100
4> example1_lid:sum(10, 20).
30

open_port()

@spec open_port(PortName, [Opt]) -> Port

PortName is one of the following:

{spawn, Command}
Start an external program. Command is the name of an external program. Command runs outside the Erlang work space unless a linked-in driver with the name Command is found.
{fd, In, Out}
Allow an Erlang process to access any currently opened ﬁle descriptors used by Erlang. The ﬁle descriptor In can be used for standard input, and the ﬁle descriptor Out can be used for standard output.

Opt is one of the following:

{packet, N}
Packets are preceded by an N (1, 2, or 4) byte length count.
stream
Messages are sent without packet lengths. The application must know how to handle these packets.
{line, Max}
Deliver messages on a one-per line basis. If the line is more than Max bytes, then it is split at Max bytes.
{cd, Dir}
Valid only for the {spawn, Command} option. The external program starts in Dir.
{env, Env}
Valid only for the {spawn, Command} option. The environment of external program is extended with the environment variables in the list Env. Env is a list of {VarName, Value} pairs, where VarName and Value are strings.