Take-A-Number Deluxe

defmodule AnnoyingPassengerAutoresponder do
  use GenServer
  # Client API

  def start_link(init_arg) do
    GenServer.start_link(__MODULE__, init_arg)
  end

  def are_we_there_yet?(pid) do
    GenServer.call(pid, :are_we_there_yet?)
  end

  # Server callbacks

  @impl GenServer
  def init(_init_arg) do
    # the initial count of questions asked is always 0
    state = 0
    {:ok, state}
  end

  @impl GenServer
  def handle_call(:are_we_there_yet?, _from, state) do
    reply =
      cond do
        state <= 3 -> "No."
        state <= 10 -> "I told you #{state} times already. No."
        true -> "..."
      end

    # increase the count of questions asked
    new_state = state + 1
    # reply to the caller
    {:reply, reply, new_state}
  end
end

التعليمات

كانت آلة أخذ الأرقام الأساسية تُبيع جيدًا جدًا، لكن بعض المستخدمين اشتكوا من افتقارها إلى ميزات متقدمة مقارنة بطرازات أخرى متاحة في السوق.

استمعت الشركة المصنّعة إلى ملاحظات المستخدمين وقررت إطلاق طراز فاخر بميزات أكثر، وأُوكلت إليك مرة أخرى مهمة كتابة البرمجيات لهذه الآلة.

تشمل الميزات الجديدة التي أُضيفت إلى الطراز الفاخر ما يلي:

• تتبّع الأرقام الموجودة حاليًا في قائمة الانتظار.
• تحديد الحد الأدنى والحد الأقصى للرقم. سيتيح ذلك استخدام عدة آلات من الطراز الفاخر لأخذ الأرقام لتنظيم اصطفاف العملاء في أقسام مختلفة داخل المنشأة نفسها، وللتمييز بين الأقسام حسب نطاق الأرقام.
• السماح لأرقام معيّنة بتخطّي قائمة الانتظار لتقديم خدمة ذات أولوية للنساء الحوامل وكبار السن.
• الإيقاف التلقائي لمنع ترك الآلة تعمل طوال عطلة نهاية الأسبوع عن غير قصد وإهدار الطاقة.

لقد نفّذ زميلك منطق العمل الخاص بالآلة بالفعل، ويمكنك العثور عليه في الوحدة TakeANumberDeluxe.State. مهمتك الآن هي تغليفه داخل GenServer.

1. تشغيل الآلة

استخدم سلوك GenServer في الوحدة TakeANumberDeluxe.

نفّذ الدالة start_link/1 ودالة الاستدعاء الراجعة اللازمة في GenServer.

الوسيط الذي يُمرَّر إلى start_link/1 هو قائمة كلمات مفتاحية. تحتوي على المفتاحين :min_number و :max_number. يجب تمرير القيم الموجودة تحت هذين المفتاحين إلى الدالة TakeANumberDeluxe.State.new/2.

إذا أرجعت الدالة TakeANumberDeluxe.State.new/2 صفًا من الشكل {:ok, state}، فعلى الآلة أن تبدأ، باستخدام الحالة المُرجَعة كحالة لها. أما إذا أرجعت صفًا من الشكل {:error, error}، فعلى الآلة أن تتوقف، مع إعطاء الخطأ المُرجَع كسبب للتوقف.

TakeANumberDeluxe.start_link(min_number: 1, max_number: 9)
# => {:ok, #PID<0.174.0>}

TakeANumberDeluxe.start_link(min_number: 9, max_number: 1)
# => {:error, :invalid_configuration}

ربما لاحظت أن الدالة TakeANumberDeluxe.State.new/2 تأخذ أيضًا وسيطًا ثالثًا اختياريًا هو auto_shutdown_timeout. سنستخدمه في الخطوة الأخيرة من هذا التمرين.

2. الإبلاغ عن حالة الآلة

نفّذ الدالة report_state/1 ودالة الاستدعاء الراجعة اللازمة في GenServer. ينبغي أن ترد الآلة على المستدعي بحالتها الحالية.

{:ok, machine} = TakeANumberDeluxe.start_link(min_number: 1, max_number: 10)
TakeANumberDeluxe.report_state(machine)
# => %TakeANumberDeluxe.State{
#      max_number: 10,
#      min_number: 1,
#      queue: %TakeANumberDeluxe.Queue{in: [], out: []},
#      auto_shutdown_timeout: :infinity,
#    }

3. إضافة أرقام جديدة إلى قائمة الانتظار

نفّذ الدالة queue_new_number/1 ودالة الاستدعاء الراجعة اللازمة في GenServer.

ينبغي أن تستدعي الدالة TakeANumberDeluxe.State.queue_new_number/1 مع الحالة الحالية للآلة.

إذا أرجعت الدالة TakeANumberDeluxe.State.queue_new_number/1 صفًا من الشكل {:ok, new_number, new_state}، فعلى الآلة أن ترد على المستدعي بالرقم الجديد وأن تجعل الحالة الجديدة حالتها. أما إذا أرجعت صفًا من الشكل {:error, error}، فعلى الآلة أن ترد على المستدعي بالخطأ دون تغيير حالتها.

{:ok, machine} = TakeANumberDeluxe.start_link(min_number: 1, max_number: 2)
TakeANumberDeluxe.queue_new_number(machine)
# => {:ok, 1}

TakeANumberDeluxe.queue_new_number(machine)
# => {:ok, 2}

TakeANumberDeluxe.queue_new_number(machine)
# => {:error, :all_possible_numbers_are_in_use}

4. خدمة الرقم التالي في قائمة الانتظار

نفّذ الدالة serve_next_queued_number/2 ودالة الاستدعاء الراجعة اللازمة في GenServer.

ينبغي أن تستدعي الدالة TakeANumberDeluxe.State.serve_next_queued_number/2 مع الحالة الحالية للآلة ووسيطها الثاني الاختياري، priority_number.

إذا أرجعت الدالة TakeANumberDeluxe.State.serve_next_queued_number/2 صفًا من الشكل {:ok, next_number, new_state}، فعلى الآلة أن ترد على المستدعي بالرقم التالي وأن تجعل الحالة الجديدة حالتها. أما إذا أرجعت صفًا من الشكل {:error, error}، فعلى الآلة أن ترد على المستدعي بالخطأ دون تغيير حالتها.

{:ok, machine} = TakeANumberDeluxe.start_link(min_number: 1, max_number: 10)
TakeANumberDeluxe.queue_new_number(machine)
# => {:ok, 1}

TakeANumberDeluxe.serve_next_queued_number(machine)
# => {:ok, 1}

TakeANumberDeluxe.serve_next_queued_number(machine)
# => {:error, :empty_queue}

5. إعادة ضبط الحالة

نفّذ الدالة reset_state/1 ودالة الاستدعاء الراجعة اللازمة في GenServer.

ينبغي أن تستدعي الدالة TakeANumberDeluxe.State.new/2 لإنشاء حالة جديدة باستخدام min_number و max_number من الحالة الحالية. وعلى الآلة أن تجعل الحالة الجديدة حالتها. ولا ينبغي أن ترد على المستدعي.

{:ok, machine} = TakeANumberDeluxe.start_link(min_number: 1, max_number: 10)

TakeANumberDeluxe.reset_state(machine)
# => :ok

6. تنفيذ الإيقاف التلقائي

عدّل بدء تشغيل الآلة. ينبغي أن تقرأ القيمة الموجودة تحت المفتاح :auto_shutdown_timeout في قائمة الكلمات المفتاحية المُمرَّرة باسم init_arg وأن تمرّرها كوسيط ثالث إلى TakeANumberDeluxe.State.new/3. استخدم القيمة الافتراضية :infinity إذا لم يُعطَ :auto_shutdown_timeout.

عدّل إعادة ضبط حالة الآلة لتمرّر أيضًا auto_shutdown_timeout إلى TakeANumberDeluxe.State.new/3.

عدّل القيم المُرجَعة من جميع دوال الاستدعاء الراجعة المنفَّذة (init/1 وجميع دوال الاستدعاء الراجعة handle_*) لتعيين مهلة. استخدم القيمة الموجودة تحت المفتاح :auto_shutdown_timeout في الحالة الحالية للآلة. لا تُضِف المهلة إلى القيمة المُرجَعة {:stop, reason} من init/1. فالمهلات لا تنطبق إلا بعد أن يبدأ الخادم حلقة الاستقبال.

نفّذ دالة استدعاء راجعة في GenServer للتعامل مع رسالة :timeout التي ستُرسَل إلى الآلة إذا لم تستقبل أي رسائل أخرى خلال المهلة المحددة. ينبغي أن تُنهي العملية بالسبب :normal.

احرص أيضًا على التعامل مع أي رسائل غير متوقعة بتجاهلها.

{:ok, machine} =
  TakeANumberDeluxe.start_link(
    min_number: 1,
    max_number: 10,
    auto_shutdown_timeout: :timer.hours(2)
  )

# after 3 hours...

TakeANumberDeluxe.queue_new_number(machine)
# => ** (exit) exited in: GenServer.call(#PID<0.171.0>, :queue_new_number, 5000)
#        ** (EXIT) no process: the process is not alive or there's no process currently associated with the given name, possibly because its application isn't started
#       (elixir 1.13.0) lib/gen_server.ex:1030: GenServer.call/3