GenMagic v1.0.1 GenMagic.Server View Source

Provides access to the underlying libmagic client, which performs file introspection.

The Server needs to be supervised, since it will terminate if it receives any unexpected error.

Link to this section Summary

Types

Represents values accepted as startup options, which can be passed to start_link/1.

Current state of the Server

t()

Represents the reference to the underlying server, as returned by :gen_statem.

Functions

Returns the default Child Specification for this Server for use in Supervisors.

Determines the type of the file provided.

Starts a new Server.

Returns status of the Server.

Stops the Server with reason :normal and timeout :infinity.

Stops the Server with the specified reason and timeout.

Link to this section Types

Link to this type

option()

View Source
option() ::
  {:name, atom() | :gen_statem.server_name()}
  | {:startup_timeout, timeout()}
  | {:process_timeout, timeout()}
  | {:recycle_threshold, non_neg_integer() | :infinity}
  | {:database_patterns, [:default | Path.t(), ...]}

Represents values accepted as startup options, which can be passed to start_link/1.

  • :name: If present, this will be the registered name for the underlying process. Note that :gen_statem requires {:local, name}, but given widespread GenServer convention, atoms are accepted and will be converted to {:local, name}.

  • :startup_timeout: Specifies how long the Server waits for the C program to initialise. However, if the underlying C program exits, then the process exits immediately.

    Can be set to :infinity.

  • :process_timeout: Specifies how long the Server waits for each request to complete.

    Can be set to :infinity.

    Please note that, if you have chosen a custom timeout value, you should also pass it when using GenMagic.Server.perform/3.

  • :recycle_threshold: Specifies the number of requests processed before the underlying C program is recycled.

    Can be set to :infinity if you do not wish for the program to be recycled.

  • :database_patterns: Specifies what magic databases to load; you can specify a list of either Path Patterns (see Path.wildcard/2) or :default to instruct the C program to load the appropriate databases.

    For example, if you have had to add custom magics, then you can set this value to:

    [:default, "path/to/my/magic"]
Link to this type

state()

View Source
state() :: :starting | :processing | :available | :recycling

Current state of the Server:

  • :pending: This is the initial state; the Server will attempt to start the underlying Port and the libmagic client, then automatically transition to either Available or Crashed.

  • :available: This is the default state. In this state the Server is able to accept requests and they will be replied in the same order.

  • :processing: This is the state the Server will be in if it is processing requests. In this state, further requests can still be lodged and they will be processed when the Server is available again.

    For proper concurrency, use a process pool like Poolboy, Sbroker, etc.

  • :recycling: This is the state the Server will be in, if its underlying C program needs to be recycled. This state is triggered whenever the cycle count reaches the defined value as per :recycle_threshold.

    In this state, the Server is able to accept requests, but they will not be processed until the underlying C server program has been started again.

Represents the reference to the underlying server, as returned by :gen_statem.

Link to this section Functions

Link to this function

child_spec(options)

View Source
child_spec([option()]) :: Supervisor.child_spec()

Returns the default Child Specification for this Server for use in Supervisors.

You can override this with Supervisor.child_spec/2 as required.

Link to this function

perform(server_ref, path, timeout \\ 5000)

View Source
perform(t(), Path.t(), timeout()) ::
  {:ok, GenMagic.Result.t()} | {:error, term()}

Determines the type of the file provided.

Link to this function

start_link(options)

View Source
start_link([option()]) :: :gen_statem.start_ret()

Starts a new Server.

See option/0 for further details.

Link to this function

status(server_ref, timeout \\ 5000)

View Source
status(t(), timeout()) :: {:ok, GenMagic.Server.Status.t()} | {:error, term()}

Returns status of the Server.

Stops the Server with reason :normal and timeout :infinity.

Link to this function

stop(server_ref, reason, timeout)

View Source
stop(t(), term(), timeout()) :: :ok

Stops the Server with the specified reason and timeout.