View Source Majic.Server (Majic v1.1.1)

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.

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.

Same as reload/2,3 but with a full restart of the underlying C port.

Reloads a Server with a new set of databases.

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.

Types

@type start_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 Majic.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 files, or of 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"]
@type 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.

@type t() :: :gen_statem.server_ref()

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

Functions

@spec child_spec([start_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 \\ 30000)

View Source
@spec perform(t(), Majic.target(), timeout()) :: Majic.result()

Determines the type of the file provided.

Link to this function

recycle(server_ref, database_patterns \\ nil, timeout \\ 30000)

View Source

Same as reload/2,3 but with a full restart of the underlying C port.

Link to this function

reload(server_ref, database_patterns \\ nil, timeout \\ 30000)

View Source

Reloads a Server with a new set of databases.

@spec start_link([start_option()]) :: :gen_statem.start_ret()

Starts a new Server.

See t:option/0 for further details.

Link to this function

status(server_ref, timeout \\ 30000)

View Source
@spec status(t(), timeout()) :: {:ok, Majic.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
@spec stop(t(), term(), timeout()) :: :ok

Stops the Server with the specified reason and timeout.